samagotchi 0.85.0 → 0.86.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d533709ed93dac5a1a65a9c023e83a50aef691542faffb1cdeefe6bfca51b5f1
-  data.tar.gz: 90cbb0c9256e751f64a36b854d6049098b694a8824a34230895e83eb383f8f74
+  metadata.gz: 9bd5a2287b8113de9eb91acc1a735e6e132f339dd1569567e7cec6e1bea6637a
+  data.tar.gz: 2cfb2f0a9cc14bb226e227fcced1ce2efb16268707953423bd1db991070e36d5
 SHA512:
-  metadata.gz: 90149bcdee28e2c2aa74c011d361aee78b652f4a0ef03c966a2fa11324181b67b8a926e3a1fe94d6d7cc8b92e62edf5d7fc67f444ebec0923fe58f7338c3c65d
-  data.tar.gz: 8884e65ab2e6a0506e15dab8ea701dda33f3a149dc6168e770ad2b885dadf7789f0d4cf2df8c22a258239b74f3da8d384c356cd72db2c66ff8154eb31819acea
+  metadata.gz: 3d5c8b88e0d4ab6fbebdb80d1705ae2904d6b5ac59b463099c9101f22161a912cbe56fe93da7cdcef672f62cc4162d212325c884f66a49aa27385a9aa71ba160
+  data.tar.gz: 3a54cc7c7629d902d1857e85b2f6fa43d2fb36805bf85ac733bfa4fba614c7a9488080dd40633c40e94ccae0749fdcce4f05c3fc7888b6e65931cd5cd492477d

data/CHANGELOG.md

@@ -8,6 +8,64 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.86.0] - 2026-10-18
+
+### Added
+
+- `chi bundle new NAME`, `chi bundle check [PATH] [--fix]` and `chi bundle test [PATH]` for writing a bundle: a
+  scaffold that checks clean and passes its test; a check that installs and loads the bundle in a sandbox and prints
+  one finding per line with a fix hint (manifest, sha256 lines, load errors with file:line, `requires_chi` floor,
+  trust, what it registers), `--fix` filling the sha lines; its tests run on chi's own Ruby and lib. `check` and
+  `test` run the bundle's code in their process: run them on code you'd install. docs/bundle-authoring.md (shipped
+  in the gem) is the first read.
+- chi tells you when a changed config.yml setting applies only after a restart ("server.port changed — applies after
+  a worker restart"; chi web's settings: after restarting chi web).
+- The `ruby` bundle (`chi bundle install ruby`, or the `dev` profile): an `execute` that ran RSpec and found no
+  examples at all (`0 examples, 0 failures`: a path, a `-e`/`--tag` filter or a `.rspec --pattern` that matched
+  nothing) steers a hint into the turn instead of leaving the run looking green.
+- A plugin's or a hook's `ask_user` takes `effects:` (option label => `:spend`, `:permit`, `:permit_wide`, `:deny`;
+  untagged = `:answer`), so a parent agent's answer is held to `guardrails.parent_answers`. The bundle test kit
+  records them (`bundle.questions.last.effects`). cost-cap 0.2.0 tags its Continue `:spend` and Stop `:deny`: under
+  `hard` a parent may only Stop it.
+
+### Changed
+
+- **What a parent agent may answer is one setting, `guardrails.parent_answers`** (`hard`, `standard`, `soft`), by
+  each option's effect, for every question: approvals, the step-limit Continue, relayed delegate approvals and plugin
+  and hook questions. **The default `soft` lets a parent give "Allow once"** (before, a parent could only deny an
+  approval); `standard` is the old default (deny, and Continue), `hard` lets a parent only deny, Stop or answer
+  plainly. A wider scope and any allow on chi's own config stay the user's. `chi send --wait`, `chi answer` and
+  `delegate_result` list what the parent may give. An invalid value warns and is `hard`. A parent's `/continue yes`
+  (`chi send ID -m '/continue yes'`, a piped `chi --attach`) is held to it too, as chi answer's.
+- SSE chunks carry chi's normalized `counts` instead of the provider's raw `payload` (and no `content`). An external
+  SSE client reading them moves to `counts` / `text` / `thinking`; `?raw=1` on the worker's stream shows the raw form.
+- At the top context bucket (no forget layer) the model's `[CONTEXT: …]` line asks for a short handoff note (state,
+  next step) instead of "summarize aggressively": "context critical — write a short handoff note (state, next step),
+  avoid large outputs, delegate broad work to subagents".
+- `guardrails.parent_approvals` and `turn.parent_continue` are removed: config.yml warns about them and names
+  `guardrails.parent_answers` (`parent_approvals: once` → `soft`; `turn.parent_continue: false` → `hard`). The old
+  pair `parent_approvals: once` with `turn.parent_continue: false` (Allow once but no Continue) has no equivalent:
+  the nearest is `hard`, which leaves both to the user.
+- The Bridge's and the relay's 403 for a refused parent answer is `parent_answer_refused`, with its `reason`
+  (was `parent_approval_refused` / `parent_continue_refused`).
+- The guardrails bundle's asks before answering chi's questions around `chi answer` (`chi-answer-piped`: `chi
+  --attach` or `chi -p` fed from a pipe or a file; `chi-answer-http`: `curl …/answer`) are the user's alone: a parent
+  agent's Allow is refused, as on chi's own config (guardrails bundle 0.9.2: its comment says so).
+
+### Fixed
+
+- `chi send --wait` no longer times out when a fallback input file carries a session command: the command's completion is recorded as that input's terminal outcome.
+- An image-only prompt sent from an attached terminal is no longer echoed again as an image line when its turn starts.
+- `chi send --queue --wait` (and a wait for a turn by its id) no longer waits until its timeout when the worker dies
+  in the middle of that turn: once the next worker settles it, the wait ends `canceled` with
+  `cancel_reason: worker_stopped` ("its worker exited mid-turn"). Another send's wait is not ended by it.
+- `chi web`'s end-of-turn re-read of the answer could keep a plugin's file ref outside the session's folder when
+  neither the worker nor the session hub named the folder (an older worker): it now takes the folder from the session
+  file, as a reload does, and drops the answer's file refs when no folder is known.
+
+Update with `chi update` (the system bundle 0.86.0, core 0.3.3, guardrails 0.9.2, cost-cap 0.2.0, dev 0.6.0 with the new ruby
+bundle 0.1.0), then restart `chi web`.
+
 ## [0.85.0] - 2026-10-18
 
 ### Added
@@ -3408,7 +3466,8 @@ and long-lived sessions.
 - A macOS desktop helper (`chi desktop install`): a "Send to chi" Service and a
   hotkey panel that send selected text or the clipboard to your sessions.
 
-[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.85.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.86.0...HEAD
+[0.86.0]: https://github.com/dm1try/samagotchi/compare/v0.85.0...v0.86.0
 [0.85.0]: https://github.com/dm1try/samagotchi/compare/v0.84.0...v0.85.0
 [0.84.0]: https://github.com/dm1try/samagotchi/compare/v0.83.0...v0.84.0
 [0.83.0]: https://github.com/dm1try/samagotchi/compare/v0.82.0...v0.83.0

data/docs/architecture.md

@@ -245,10 +245,33 @@ process that already owns the `Engine`); every worker starts it, and it exposes:
   too-old reconnects, and cursors from another worker's epoch, receive a `reset` marker carrying
   `session_state_snapshot`. `?snapshot=1` joins with a snapshot frame instead of a replay;
   `?client_id=` names whose stream it is (`Bridge#open_streams_except`, used by `POST /exit`).
+  Each event goes out as clients get it (`Bridge::ClientEvent.project`, in `SSEWriter#write_event`, live
+  and replayed alike); only a `generation_chunk` changes, to chi's own format (the chunk contract below).
+  `?raw=1` writes events as the engine emitted them, for debugging on the worker's port: `chi web`'s
+  `/api/sessions/:id/stream` never passes it on (`Web::App#stream_query`).
   An attached terminal's stream (`EventStream` with `rediscover:`) looks for the session's live
   worker whenever it drops: a new one (a restart) is followed from its snapshot, and the terminal
   sends its requests there (`worker_changed`); it gives up after ~12 s, or at once when the session
   was stopped.
+
+  The wire chunk (the contract; the engine's own event keeps the provider's `payload` and the raw `content`):
+
+  ```
+  event: generation_chunk
+  data: {"type":"generation_chunk","iteration":2,"text":"…","thinking":"",
+         "tool_call":true,                                   // only when set
+         "counts":{"prompt_tokens":489,"completion_tokens":12,
+                   "total_tokens":501,"context_window_tokens":32768},  // only when the server reported counts
+         "event_seq":812}
+  ```
+
+  `counts` is `ContextUsage.normalize` of the provider's payload without `ctx_pct` (normalize computes it
+  without the session's LLM context budget; a client counts `total_tokens` against the window or budget, as
+  `ContextStatus#generation_done` does for the TUI) and with its nil keys left out: cumulative for the
+  request, a missing key means unknown (never 0), `prompt_tokens` includes cached tokens, and
+  `context_window_tokens` is there only when the payload reported a window itself (llama.cpp's `/completion`
+  doesn't: the client uses `generation_started`'s). Unknown provider fields never cross; a field is added here
+  when a client needs it, never as a catch-all bag. Details: [internals/context-telemetry.md](internals/context-telemetry.md).
 - `POST /session/:id/turn` — fire-and-forget turn creation; returns `202` with an `enqueued_id`
   (delivery is at-least-once via the worker's file-IPC input path — it never calls `run_turn`
   across the HTTP boundary). Only the bridge's own session: another id, in the path or the body's
@@ -270,8 +293,11 @@ process that already owns the `Engine`); every worker starts it, and it exposes:
   arrives as `:recap_ready`. Answers mid-turn too.
 - `POST /session/:id/answer` — answer the pending question; `200`, `409` when another client
   answered first or it is gone, `400` for an invalid selection. With `client_id: "cli:answer"`
-  (`chi answer`, a parent agent) an allow on an approval beyond the worker's
-  `guardrails.parent_approvals` is `403 parent_approval_refused`, the question still open.
+  (`chi answer`, a parent agent) the answer is checked by `Guardrails::ParentPolicy` in
+  `QuestionDesk#answer`: the question carries each option's effect (`effects`, set by its asker:
+  `Approval.payload`, `ContinueOffer`, `Relay.card`; derived for an untagged one) and `user_only`,
+  and an option beyond the worker's `guardrails.parent_answers` is `403 parent_answer_refused`
+  (with its `reason`), the question still open. `chi answer` makes the same check first.
 - `POST /session/:id/question/dismiss` — leave the question unanswered (an approval: denied);
   `200`, or `409` when it is no longer pending.
 - `POST /session/:id/tasks/stop` — `{task_id}`: stop a background task as the user
@@ -295,7 +321,7 @@ process that already owns the `Engine`); every worker starts it, and it exposes:
   pending question's `relayed_to` mark (`QuestionDesk#annotate`, `:question_relay`); `answered`
   makes the child ask its parent's Bridge for the answer (`RelayVerifier`) and take it only for
   this child and the question pending now. `200`, `409` no longer pending, `403` a parent agent's
-  allow beyond the child's `guardrails.parent_approvals`, `422 relay_unverified` (the question
+  pick beyond the child's own `guardrails.parent_answers` (`parent_answer_refused`), `422 relay_unverified` (the question
   stays open).
 - `POST /session/:id/relay/status` — on a parent's worker, `{relay_id}`: what its `RelayDesk`
   (memory only) holds for that relay (`child_id`, `child_question_id`, `state`, `answer`, `by`);
@@ -369,7 +395,8 @@ The page's frequent reads of `GET /api/sessions/:id` stay light too:
   The page binds an answer's `display_refs` to its bubble (`answer_refs.js`: on a reload's render and on this
   read's re-render) and pairs them with the bubble's links and text before the `path:line` scan. A file ref outside the
   session's folder is dropped, as a reload drops it: the folder `/tail` names, else (an older worker) the hub's
-  session list entry's.
+  session list entry's, else (refs to check, no hub entry) the session file's; with no folder known at all, every
+  file ref is dropped rather than shown unchecked.
   A plugin tool's row refs (`refs`, `RowRefs`) ride its tool events and, on a reload, its part (saved as
   `tool_refs`); `turn_view.js` binds them to the row's title (`refs.js bindRowRefs`: the first on the title,
   the others in its menu).
@@ -446,7 +473,9 @@ both go through `ToolRunner` (events, hooks, veto, output cap) and
 chat `tool_calls`) are built by one table, `Tools::BuiltinCalls`, from the
 parsed `{name, args}` (derived from `TOOL_SCHEMAS`), so a call looks the same to
 hooks and tools whichever model made it. Both loops' `generation_chunk` carries
-`thinking:`, `text:` and `content:` (both): the chat loop's thinking is the
+`thinking:`, `text:`, `content:` and the provider's `payload:` (the Bridge projects it for its
+clients: `text`, `thinking`, `tool_call` and chi's `counts`, no `payload` or `content`; see the
+Bridge's stream above): the chat loop's thinking is the
 server's `reasoning_content`; the raw-prompt loop splits each generation's
 stream with a fresh `ThoughtStreamSplitter` (Qwen's `<think>` and Gemma's
 `<|channel>thought … <channel|>` are thinking, tool-call bodies are dropped

data/docs/bundle-authoring.md

@@ -0,0 +1,125 @@
+# Writing a bundle
+
+Read this first when someone asks for new chi functionality "as a bundle". It is the short path: the loop, the
+files, what a hook sees, how to test, and what goes wrong. The full references are in this same `docs/` folder:
+[plugins.md](plugins.md) (the `chi.*` API and `ctx`) and [hooks.md](hooks.md) (every event's fields).
+
+## The loop
+
+```
+chi bundle new my-bundle     # ./my-bundle: manifest.yml, plugin.rb, test/my_bundle_test.rb, README.md
+cd my-bundle                 # edit plugin.rb and the test
+chi bundle test              # the tests, on chi's own Ruby and lib (exit status: the tests')
+chi bundle check --fix       # manifest, files, shas (--fix rewrites them), requires_chi, install + load in a sandbox
+chi bundle install .         # into the user's chi; a NEW session loads it (a running one doesn't)
+```
+
+`check` prints one finding per line, `error|warn|info CODE file[:line]: message (fix: hint)`, and exits 1 on any
+error. Run it after every edit: an install takes exactly what it checks. It installs into a temp sandbox, not
+the user's config or state, but `check` and `test` run the bundle's plugin and hooks in their own process, as
+written: run them on code you'd install.
+
+## The files
+
+```yaml
+# manifest.yml
+name: my-bundle              # a plain name; chi bundle install takes it from here
+version: 0.1.0
+scope: system
+description: "What it adds, in one line"
+requires_chi: ">= 0.85.0"    # the chi it needs (new writes the running one; check warns when a call needs newer)
+plugin:
+  file: plugin.rb
+  sha256: sha256:<hex>       # `chi bundle check --fix` fills it; never compute it by hand
+# files:                     # memories it installs (top-level *.md); without files: every *.md but README & co.
+#   my_notes.md: sha256:<hex>
+# hooks:                     # hooks/*.rb files (a plugin's chi.on is usually simpler)
+# needs: [gh]                # outside commands it relies on
+```
+
+`plugin.rb` defines `class Plugin` with `register(chi)`; `initialize(settings)` (optional) gets config.yml
+`bundles: my-bundle:` as a Hash with string keys, once, when the plugin loads. A value a session may set
+(`chi --set my-bundle.KEY=V`, listed in the manifest's `session_settings:`) is read from `ctx.settings` at call
+time. `chi bundle check --set KEY=VALUE` gives the sandboxed load a setting.
+
+## What a hook sees
+
+`chi.on(event) { |event, ctx| … }` gets a Hash. The events, in a turn's order: `session_start`, `before_turn`,
+`before_generation`, `generation_progress`, `after_generation`, `before_tool_call`, `after_tool_call`,
+`after_turn`, `session_end` (the fields of each: [hooks.md, Hook Events](hooks.md#hook-events)). A symbol not in
+that list is never fired (`check` warns). The two a bundle wants most, for an `execute`:
+
+```ruby
+# before_tool_call: vote on the call before it runs
+{ type: :before_tool_call, iteration: 1,
+  call: { name: "execute", content: "rm -rf build" }, params: "execute rm -rf build",
+  guardrail: verdict,        # event[:guardrail].deny!("why") / .ask!("why"); ctx.stop_turn denies and stops the turn
+  context: { cwd: "/work", repo_root: nil, branch: nil, session_id: "…", interface: :worker, origin: nil },
+  targets: { command: "rm -rf build", paths: [], cwd: "/work", repo_root: nil, outside_repo: false, git_dirs: [] },
+  blocked: false, block_reason: nil }
+
+# after_tool_call: what it did
+{ type: :after_tool_call, iteration: 1, tool: "execute", status: "error",   # "ok" | "error" | "blocked" | "stopped"
+  call: { name: "execute", content: "make test" }, elapsed_ms: 812,
+  result: "stdout:\nok\n\nstderr:\n1 failed\n\nexit: 1",                    # the tool's own text, never cut
+  output: "[execute]\nstdout:\n…" }                                          # what the model reads: may be cut
+```
+
+Match on `result:`, not `output:`. An execute's result is its `stdout:` and `stderr:` blocks (each left out when
+empty), then `exit: N` (`exit: 0 (no output)` when both were empty); a non-zero exit makes `status:` `"error"`.
+Act through `ctx`: `ctx.notify(text, level: :warn)`, `ctx.steer(text)` (a line the model reads before its next
+step), `ctx.card(…)`, `ctx.stop_turn(reason)`, `ctx.ask_user(…)`, `ctx.data_dir` (the bundle's own folder),
+`ctx.cwd`, `ctx.log`. In a test, each recorded notice, steer or stop names its hook as `"plugin.rb (bundle
+my-bundle)"`, the plugin's label (a `hooks/x.rb` file's is `"x.rb (bundle my-bundle)"`).
+
+## Testing it
+
+`chi bundle new` writes a Minitest test that passes as written: copy its shape. The kit (`samagotchi/testing`)
+loads the bundle's source through chi's own loaders, in a sandbox (temp HOME, config and state), and records what
+it did at chi's edges:
+
+```ruby
+bundle = load_bundle(BUNDLE, settings: { "greeting" => "hi" })   # in a Samagotchi::Testing::Case test
+bundle.command("/my-bundle chi")                     # → what the command returned
+bundle.fire(:after_tool_call, tool: "execute", status: "error", result: "exit: 1 (no output)", call: { … })
+bundle.tool_call({ name: "execute", content: "rm -rf /" }).deny?   # before_tool_call hooks, through the real gate
+bundle.tool("my_tool", path: "a.txt")                # a chi.tool, as the model calls it
+bundle.notices, bundle.steers, bundle.cards, bundle.stops, bundle.questions   # what it did
+bundle.answer({ selected: "yes" }); bundle.model_answers << "text"           # ask_user / ask_model answers
+bundle.http.stub(:get, "https://api.example/x", json: { ok: true })          # ctx.http, never the network
+bundle.set(cwd: dir, running: false); sandbox.config(hash); sandbox.fake_executable("gh", "echo '{}'")
+bundle.install                                        # installed as chi installs it: warnings, load failures
+```
+
+The full list is in [plugins.md, Testing a bundle](plugins.md#testing-a-bundle-experimental). The kit is
+experimental (it may change before chi 1.0). If a test needs a fake of chi's own (a stub of a `Samagotchi::`
+class, a hand-built `ctx`), that is a gap in the kit: say so to the user rather than reaching into chi.
+
+## Pitfalls
+
+- **Shas.** Every file the manifest names has a sha256 line, and an edit makes it stale: the install then warns
+  of a checksum mismatch, and a line with no sha installs unchecked. `chi bundle check --fix` rewrites them; run it
+  after the last edit.
+- **requires_chi.** Use the chi the user runs (`chi --version`). `check` warns when the plugin calls something
+  newer than the floor (`ctx.http` needs 0.80.0, `ctx.cost` 0.83.0).
+- **trust_level.** Leave it out. `reviewed` / `trusted` are for someone who reviewed the bundle, not its author.
+- **Restart.** A session loads bundles when it starts: after an install or a settings change, the user starts a
+  new session (or `chi sessions restart ID`).
+- **chi's internals.** A bundle may use `chi.*`, `ctx` and the names
+  [plugins.md, Stable for bundles](plugins.md#stable-for-bundles) lists; any other `Samagotchi::` name may change
+  in any release (`check` warns: `boundary`).
+- **Load errors.** A plugin that raises at load is skipped and the session goes on: `check` shows the error at its
+  `plugin.rb:LINE`.
+
+## Verifying it live
+
+After `chi bundle install .`, one real session shows it works with the user's chi:
+
+```
+chi send --new --wait --format json --dir /tmp/try -m "/my-bundle chi"   # the JSON names the session id
+grep plugin_loaded ~/.local/state/samagotchi/samagotchi.log | tail -1    # bundle=my-bundle commands=1 hooks=1
+chi sessions delete --force SESSION_ID                                    # leave no test session behind
+```
+
+(`$XDG_STATE_HOME/samagotchi/samagotchi.log` when `XDG_STATE_HOME` is set.) Then tell the user what it adds,
+how to use it, and that a new session picks it up.

data/docs/cli.md

@@ -19,12 +19,12 @@
 - `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 | --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 — to an idle session whose last turn already ended, that ended turn's reply or end comes back; `--wait --turn T ID` with no message waits for exactly turn T, whether running, queued or last ended; `--format json` includes its `turn_id` when known, for waiting again after exit 3 or 4; 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 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` (`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 desktop install|upgrade|uninstall|status` — the macOS "Send to chi" helper: a Service and a ⌃⌥⌘N hotkey that send text or images to a session (live, stopped or new) as a message (⏎, a turn runs) or a context note (⌘⏎) (see [Desktop helper](desktop.md))
 - `chi models [--format text|json] [--timeout S] [TEXT]` — list the models every configured host offers, as the names `--model` takes (see [Listing the models](#listing-the-models))
 - `chi self` — print version, source dir (checkout or installed gem), config/memory/session paths, model/host and bundles. Run by a session's `execute`, the `model` row (and host, loop, profile, thinking, served model) is **that session's** model, labelled `(this session <id8>; default …)`; elsewhere it is the default, `(default)`. `model key` is the memory overlay key (`<name>.<key>.md`), and `model notes` the model notes a prompt of that model loads (`model_notes_deepseek (system, 612 chars)`, `none`; inside a session its `--mute` list is left out). `chi self --model` prints only the model a new session starts on, an alias resolved to its target (the desktop helper's hint)
 - `chi update [--dry-run] [--no-gem] [--no-bundles] [--no-desktop]` — update an installed chi: the gem, the system bundle, the shipped bundles you installed and the desktop helper, in one table (see [Updating](#updating))
-- `chi bundle install|upgrade|uninstall|status|diff|list|build|trash` — 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
+- `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)
 
 ### First setup
 
@@ -87,6 +87,39 @@ chi bootstrap                            # try localhost 8080, 11434, 1234, 8000
   A bundle that fails to install makes the exit 1. `--dry-run` says what it
   would install.
 
+### Writing a bundle: new, test, check
+
+The loop for a bundle you're writing (the whole path: [bundle-authoring.md](bundle-authoring.md)):
+
+- `chi bundle new NAME [--dir DIR]` writes `DIR/NAME/` (default `./NAME`; refused when it exists; `NAME` is
+  `a-z` first, then `a-z`, `0-9`, `-`, `_`, as a slash command): `manifest.yml` (a block-form `plugin:` entry with
+  its sha filled, `requires_chi: ">= <this chi>"`), `plugin.rb` (a `/NAME` command and an `after_tool_call` hook),
+  `test/NAME_test.rb` (Minitest on the bundle test kit, passing as written) and `README.md`, then prints the next
+  steps. Exit 1 when it refuses, 2 for usage.
+- `chi bundle test [PATH] [-- ARGS]` runs the bundle's tests on the Ruby and the lib chi runs on, outside any
+  Bundler env: `test/**/*_test.rb` on Minitest (`-r samagotchi/testing/minitest`), or else `spec/` on RSpec with
+  the kit (`--options /dev/null -r samagotchi/testing/rspec`, as `rake bundles:specs`). `ARGS` go to the runner
+  (`-- -n /name/`). Exit status: the tests'; 1 with no tests; 2 for usage, or when minitest / rspec doesn't load on
+  chi's Ruby. The tests run the bundle's code as written, with your environment (the kit sandboxes each
+  test's HOME and XDG dirs, not the process).
+- `chi bundle check [PATH] [--fix] [--set KEY=VALUE]` (PATH defaults to `.`) checks it as an install takes it, one
+  finding per line, `error|warn|info CODE file[:line]: message (fix: hint)`, then `ok|failed: N errors, N
+  warnings`. Exit 1 on any error, 0 otherwise, 2 for usage. It installs and loads the bundle in a temp sandbox
+  (HOME, config and state), not in yours, but in chi's own process: the plugin's and hooks' code runs as written,
+  so run it (and `test`) on code you'd install. The codes, in order: `manifest` (a parse error, verbatim; the run
+  stops), `missing-file`, `unlisted` (warn: a file an install leaves out, by `MemoryFiles`' rules, so a README
+  isn't one), `sha` (a stale or placeholder sha, or a plugin / hook / script entry with no sha line; `--fix`
+  rewrites the first two and prints `fixed sha FILE → sha256:…`), `requires-chi` (this chi doesn't satisfy it:
+  error; missing on a bundle with code: warn), `requires-chi-floor` (warn: the plugin calls an API newer than the
+  oldest chi `requires_chi` admits, from `Plugin::Api::SINCE`), `trust` (warn: `trust_level: reviewed|trusted` on a
+  bundle chi doesn't ship), `clash` (warn: a name chi ships, or one installed from elsewhere; the sandboxed install
+  then forces), `install` (each Installer warning, a `needs` one as warn, and each plugin or hook load failure at
+  the source `file:line`; skipped while a placeholder sha is unfilled), `registered` (info: each command, tool,
+  hook with its priority, init, toolkit, tool source and peer source), `hook-event` (warn: a `chi.on` event chi
+  never fires), `boundary` (warn: a `Samagotchi::` name outside "Stable for bundles"; a shipped bundle's listed
+  exceptions aside) and `tests` (info: how to run them, or "no tests"). `--set KEY=VALUE` (repeatable, typed as
+  `chi --set`) goes to `bundles: <name>:` in the sandbox's config.yml.
+
 ### Listing the models
 
 `chi models` asks every host in `hosts:` for its models, in parallel, and prints the names `--model` (and
@@ -1153,7 +1186,9 @@ Behavior notes:
 - Stop keeps the interrupted turn's work in the conversation, as a Ctrl-C or a new prompt does, with a note for the
   model that it wasn't continued (or your reason); `!rollback` still erases it.
 - `--non-interactive` (`chi -p`) has nobody to ask: the turn ends there. A `chi send --wait` on a session nobody can
-  answer (an older worker) reports `limit` (exit 1) with how to continue it: `chi send ID -m '/continue yes'`.
+  answer (an older worker) reports `limit` (exit 1) with how to continue it: `chi send ID -m '/continue yes'`
+  (not under `guardrails.parent_answers: hard`: a parent agent's `/continue yes`, sent with `chi send` or typed into a
+  piped `chi --attach`, is held to it as `chi answer --option Continue` is, and refused there).
 - The check-in bundle's card closes as the turn ends, before the step-limit question opens, so the two never stand
   together; with check-in's default `after: 50` and the limit of 300 a long turn shows check-in cards (at 50, 100, …)
   well before it.

data/docs/configuration.md

@@ -131,7 +131,8 @@ The config reader checks the file's modification time and size whenever a
 setting is read. That makes a changed value available to a live reader; it
 does not reload every object that already holds a snapshot. "Worker start"
 includes a worker respawn. A running turn keeps the settings it already
-resolved.
+resolved. chi tells you when a changed setting applies only after a worker
+or `chi web` restart.
 
 | Key | Applies | Note |
 |---|---|---|
@@ -144,6 +145,7 @@ resolved.
 | `models.<key>.profile` | Session start or `/model` | It is resolved when that model is selected; editing it does not switch the current model's profile by itself. |
 | Other `models.<key>.*` settings | Next turn or model lookup | Sampling, thinking, vision, context, window, price and steer settings are resolved from the file for their next use. |
 | `thinking.level` | Next turn start | A session's own `/thinking` level is saved in that session and takes precedence; a running turn keeps its level. |
+| `turn.max_iterations` | Next turn start | The configured step limit is resolved when each turn begins. |
 | `cache.*` | Next request or turn-end warm-up | Cache key and TTL are read for a request; warm-up is checked after a turn. |
 | `retry.max`, `retry.base_delay`, `retry.max_delay` | Worker start | The client's network retry policy is built with its HTTP client. |
 | `retry.empty_answer` | Next empty-answer retry | It is checked when a turn needs to retry an empty answer. |
@@ -154,12 +156,12 @@ resolved.
 | `thinking.turn_preamble`, `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` | 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. |
 | `context.every_seconds` | Next context poll | The poller checks it for each source that has no explicit interval. |
-| `guardrails.*` | Next tool call or approval | Guardrail rules and disable lists are reloaded when the config file changes; rule settings take effect on that evaluation. |
+| `guardrails.*` | Next tool call or approval | Guardrail rules and disable lists are reloaded when the config file changes; rule settings take effect on that evaluation. `guardrails.parent_answers` is checked when a parent answers a question. |
 | `hooks`, `bundles` | Worker start | Hooks, plugins and their bundle settings load with the engine. |
 | `recap.*` | Worker start | The engine builds its recap job once. |
 | `session.shared` | Next `chi` invocation | It selects attached-worker or in-process mode for that invocation. |
 | `session.idle_exit_minutes`, `session.keep_empty`, `session.max_children`, `session.delegate_reports`, `session.max_wakes` | Worker start or next matching lifecycle decision | Existing workers keep their idle-exit timer; the other values are read for the next corresponding decision. |
-| `session.retention_*` | Next retention sweep | `chi web` sweeps on its configured schedule and on `GET /api/sessions`; `chi sessions prune` uses the values for that invocation. |
+| `session.retention_*`, `session.max_count`, `session.keep_status`, `session.sweep_interval_hours` | Next retention sweep | `chi web` sweeps on its configured schedule and on `GET /api/sessions`; `chi sessions prune` uses the values for that invocation. The sweep interval is checked on the next hub tick. |
 | `web.*` | `chi web` start | Restart `chi web` to change its bind address, port or page settings. |
 | `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. |
@@ -1631,7 +1633,7 @@ column says so, a `--kebab-name` flag. The maps (`hosts:`, `models:`,
 | `guardrails.enabled` | `true` | | `false`: no rules, and hooks' asks are dropped (a deny still applies). config.yml only: a worker unsets any `SAMAGOTCHI_GUARDRAILS_*` it inherits. See [Guardrails](guardrails.md). |
 | `guardrails.mode` | `auto` | | Which rules vote: `auto` leaves out the rules tagged `modes: [strict]` (in the guardrails bundle: `git rebase`, writes and git outside the session's repo); `strict` runs them all. An unknown value warns and is `auto`. config.yml only. See [Guardrails](guardrails.md#modes). |
 | `guardrails.small_models` | `auto` | | Which models get the `models: small` rules: `auto` (32B or less by the size in the name, an MoE's active size), a list of globs, or `[]`. config.yml only. See [Guardrails](guardrails.md#rules-for-some-models). |
-| `guardrails.parent_approvals` | `off` | | What `chi answer` lets a parent agent allow on an approval: `off` (deny only) or `once` ("Allow once", never a wider scope). config.yml only: no environment variable (a parent can still pick the config dir with `XDG_CONFIG_HOME`). A convention for an honest parent, not a security boundary. See [Guardrails](guardrails.md#approvals-from-a-parent-agent). |
+| `guardrails.parent_answers` | `soft` | | Which options a parent agent (`chi answer`) may pick on a session's question, by their effect: `hard` (a deny, a Stop, a plain answer), `standard` (+ Continue and other spending options), `soft` (+ "Allow once"); never a wider scope or an allow on chi's own config. An invalid value warns and is `hard`. Replaces `guardrails.parent_approvals` and `turn.parent_continue`. config.yml only: no environment variable (a parent can still pick the config dir with `XDG_CONFIG_HOME`). A convention for an honest parent, not a security boundary. See [Guardrails](guardrails.md#answers-from-a-parent-agent). |
 | `log.file` | state dir | yes | See "Debug Log File". |
 | `log.disable` | `false` | yes | No file logging. |
 | `log.level` | `info` | yes | `debug`, `info`, `warn`, `error`. |
@@ -1675,7 +1677,6 @@ column says so, a `--kebab-name` flag. The maps (`hosts:`, `models:`,
 | `steer.cut_after` | `20` | | Seconds a generation must have streamed only thinking before a message sent as a cut (`/cut TEXT`, `chi send --cut`) cuts it; other messages go in at the next step; `0` = never. `models.<key>.steer_cut_after` and `hosts.<name>.steer_cut_after` come first; see [Messages during a running turn](#messages-during-a-running-turn-steer-and-cut). |
 | `models.<key>.steer_cut_after`, `hosts.<name>.steer_cut_after` | none | | A model's or host's seconds a cut waits for its thinking: whole seconds, `0` = never (e.g. a slow local thinker). `/model` shows the resolved one. See [Messages during a running turn](#messages-during-a-running-turn-steer-and-cut). |
 | `turn.max_iterations` | `300` | | A turn's step limit: model ↔ tool rounds before it stops and asks to continue (an integer ≥ 1). `--no-interrupt` turns get the larger of 1000 and this. See [CLI: Iteration Limit Behavior](cli.md#iteration-limit-behavior). |
-| `turn.parent_continue` | `true` | | Whether a parent agent (`chi answer`) may answer Continue to a session's step-limit question; `false`: Stop only. config.yml only: no environment variable. See [Sub-agent](sub-agent.md) and [Guardrails](guardrails.md#approvals-from-a-parent-agent). |
 | `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`). |

data/docs/guardrails.md

@@ -67,8 +67,9 @@ Who answers:
   answerable too, the first answer wins. The parent's model sees only the
   outcome.
 - A parent agent running chi as a sub-agent (`chi send --wait` exits 3 with
-  the approval): `chi answer` may deny it, never allow it by default, or leave
-  it for the user. See [Approvals from a parent agent](#approvals-from-a-parent-agent).
+  the approval): `chi answer` may deny it, give "Allow once" under
+  `guardrails.parent_answers: soft` (the default; never a wider scope), or
+  leave it for the user. See [Answers from a parent agent](#answers-from-a-parent-agent).
 
 The model gets one line on a deny. A rule's or hook's deny reads
 `[execute] Error: denied by guardrail (rule git-push, bundle guardrails): git push publishes commits. The user was not asked. Do not retry it or reach the same result another way; ask the user how to proceed.`
@@ -99,39 +100,64 @@ with one warning, and chi starts with no stored approvals (more asks, nothing lo
 `/guardrails` lists the rules and approvals; `/guardrails revoke N` removes one.
 The file tools can't write the store.
 
-### Approvals from a parent agent
+### Answers from a parent agent
 
-A chi parent's `delegate` children don't need any of this: their approvals go
-to the user on the parent's own card (the approval relay). This section is the
-path for other agents, and for a chi parent that can't host the relay (a
-`--no-shared` REPL, `--non-interactive`): there the model gets the approval
+A chi parent's `delegate` children don't need any of this for approvals: they
+go to the user on the parent's own card (the approval relay). This section is
+the path for other agents, and for a chi parent that can't host the relay (a
+`--no-shared` REPL, `--non-interactive`): there the model gets the question
 block and the rules below. With the relay, the same rules still hold for a
 parent model that answers its own relay card (a piped or marked `chi --attach`
 on the parent): that answer is a parent agent's, checked by the parent and
 again by the child.
 
 When another agent (Claude Code, Codex, a script) runs chi with
-`chi send --wait`, an approval comes back to it as exit 3 with `kind:
-approval`, and `chi answer` answers it. A rule with `verdict: ask` means "ask
-me", so by default a parent may only deny: `--option Deny --text "why"`,
-`--text` alone, or `--dismiss`. An Allow is refused (exit 1, `allowing a tool
-call is up to the user: deny it (--option Deny --text WHY), and tell your
-user`). The question block chi prints for an approval says the same: its
-command is a deny, with no `--option N` and no `chi --attach`.
+`chi send --wait`, a question comes back to it as exit 3 and `chi answer`
+answers it. Every question's options carry an **effect**, set by whoever asks:
+
+- `answer`: a plain choice (the model's own questions, an untagged plugin or
+  hook option);
+- `deny`: Deny on an approval, Stop on the step-limit question or a plugin's
+  stop option;
+- `spend`: more time and tokens, no new permission (Continue on the step-limit
+  question, cost-cap's Continue);
+- `permit`: one tool call (an approval's "Allow once");
+- `permit_wide`: more than one call (this session, this repo or directory,
+  the rule).
+
+One setting says which effects a parent may pick:
 
 ```yaml
 guardrails:
-  parent_approvals: once    # default off
+  parent_answers: soft    # hard | standard | soft (the default)
 ```
 
-`once` lets `chi answer --option "Allow once"` through, picked by the
-option's scope, not its label; the wider scopes (this session, this repo or
-directory, the rule) stay with the web and the terminal. An approval that
-doesn't offer "once" can't be allowed from a parent, and neither can one whose
-offered scopes are missing or don't fit its options: then only Deny goes.
+- `hard`: `deny` and `answer` only. A parent can deny an approval
+  (`--option Deny --text "why"`, `--text` alone or `--dismiss`), Stop a
+  step-limit question and answer plain questions.
+- `standard`: also `spend`: a parent may Continue a turn (or cost-cap's cap).
+- `soft` (the default): also `permit`: `chi answer --option "Allow once"`
+  goes through, picked by the option's scope, not its label.
+
+A parent never picks `permit_wide`: the wider scopes stay with the web and the
+terminal. An approval that doesn't offer "once" can't be allowed from a
+parent, and neither can one whose offered scopes are missing or don't fit its
+options: then only Deny goes. A refused pick exits 1 with what to do instead
+(`only Allow once (guardrails.parent_answers: soft) can be given here: deny it
+(--option Deny --text WHY), and tell your user`), never how to allow it. The
+question block chi prints says what the parent may give: under `soft` an
+approval's block lists the Allow once command next to the deny; under
+`standard` and `hard` it says allowing is up to the user. An invalid value
+warns and is `hard`.
+
+`soft` suits a capable parent model: it can let a child run one more command
+it asked about, still with every guardrail rule in force. For a weak or
+unknown parent model, set `standard` or `hard` (and see
+[chi-nah](#an-external-guard-chi-nah) for a deterministic guard on the calls
+themselves).
 
 A child that has to work in another folder (`write-outside-repo`,
-`git-outside-repo`) is denied this way too. Start it in that folder instead
+`git-outside-repo`) gets at most Allow once per call this way. Start it in that folder instead
 (`chi send --new --dir PATH`), or have your user allow "rule … in this repo"
 once on the web (it is stored for later sessions in that repo), or switch the
 rules off: `guardrails: {disable: [write-outside-repo, git-outside-repo]}`.
@@ -140,16 +166,17 @@ Whatever the setting, a parent can't allow a call on chi's own files: a
 `write`, `edit` or `execute` on the config dir (config.yml, installed bundles'
 rules), the hooks dir or the approval store, by its rule (`chi-config`,
 `chi-hooks`, `shell-touches-chi`), its paths or its command. "Allow once" on a
-config.yml rewrite would allow everything from then on, so those stay with the
-user: `chi answer` and the worker refuse the allow with `only the user can
-allow it`.
+config.yml rewrite would allow everything from then on, so those questions are
+the user's alone (`user_only`): `chi answer` and the worker refuse the allow
+with `only the user can allow it`. The same holds for the guardrails bundle's
+other user-only rules (`chi-context-cmd`, `chi-broadcast`,
+`prompt-memory-write`, `model-overlay-write`, and `chi-answer-piped` /
+`chi-answer-http`, which answer a grandchild's question as the user).
 
-A turn's step-limit question (kind `continue`) isn't an approval: Continue
-grants no permission, so a parent may answer it either way by default.
-`turn.parent_continue: false` (config.yml only, like `parent_approvals`)
-makes parents stop-only. See [chi as a sub-agent](sub-agent.md#the-step-limit).
+A plugin's or a hook's question (`ask_user`) tags its options the same way
+(`effects:`, see [Plugins](plugins.md)); an untagged one is a plain `answer`.
 
-The guardrails settings (`enabled`, `mode`, `small_models`, `parent_approvals`) are
+The guardrails settings (`enabled`, `mode`, `small_models`, `parent_answers`) are
 read from config.yml only: they have no environment variable, and a worker
 chi starts unsets every `SAMAGOTCHI_GUARDRAILS_*` it would inherit. What a
 parent's environment does choose is the config dir: `XDG_CONFIG_HOME` picks
@@ -159,11 +186,11 @@ points at (a relative one made absolute from the parent's directory). chi
 doesn't record the config dir per session.
 
 The worker checks it too. `chi answer` marks its answers as a parent's
-(`client_id: "cli:answer"`), and the worker's Bridge refuses such an allow
-beyond what the *worker's* config.yml permits (`403 parent_approval_refused`;
-`chi answer` exits 1 with the reason), checked against the question pending
-at that moment. Answers from the web and an attached terminal keep every
-scope.
+(`client_id: "cli:answer"`), and the worker's Bridge refuses such a pick
+beyond what the *worker's* config.yml permits (`403 parent_answer_refused`
+with its `reason`; `chi answer` exits 1 with the line), checked against the
+question pending at that moment. Answers from the web and an attached
+terminal keep every option.
 
 A parent may also type its answer into chi itself: a piped `chi --attach ID`
 or `printf '2\n' | chi --no-shared -p …`. So chi treats an answer as a
@@ -511,7 +538,8 @@ only by the user: these change a model's system prompt for later sessions (see
 `shell-touches-chi`'s text heuristic); and answering chi's
 questions around `chi answer`: `chi --attach` or `chi -p` with stdin from a
 pipe, a here-string or a file, not `/dev/null` (`chi-answer-piped`), and `curl`/`wget` to a
-session's `/answer` route (`chi-answer-http`), both once or for the session.
+session's `/answer` route (`chi-answer-http`), both once or for the session, and only by the
+user (a parent agent allowing one would answer as the user).
 `chi answer` itself isn't asked about. It denies writes into `.git/hooks`.
 
 In strict mode (`guardrails: { mode: strict }`) it also asks before `git