samagotchi 0.85.0 → 0.86.0

data/docs/hooks.md

@@ -89,9 +89,12 @@ class Watchful
       # A single-select question through the question flow (REPL, attached
       # TUI, web); returns {selected: [...], freeform:, selected_indices:}
       # or nil when there is no one to ask (--non-interactive), the
-      # question was dismissed, or the options were not 2-8 strings.
+      # question was dismissed, or the options (or effects) were invalid.
+      # effects: says what an option does for a parent agent's answer (see
+      # below): Run lets one call through, so it is :permit.
       answer = event[:ask_user].call(question: "#{event[:call][:name]}: #{event[:params]}\nRun it?",
-                                     options: ["Run", "Deny"], header: "my guard", allow_freeform: false)
+                                     options: ["Run", "Deny"], header: "my guard", allow_freeform: false,
+                                     effects: { "Run" => :permit, "Deny" => :deny })
       event[:guardrail].deny!("the user said no") unless answer&.dig(:selected)&.first == "Run"
     when :before_generation
       # Cancel the running turn: a warn notice with the reason, then the
@@ -112,6 +115,19 @@ class Watchful
 end
 ```
 
+**Tag the options that spend or permit.** A question can be answered by a
+parent agent (`chi answer`, a piped `chi --attach`), and
+`guardrails.parent_answers` decides which options it may pick by their
+`effects:` (label => effect): `:spend` (more time or money: a Continue),
+`:permit` (one call), `:permit_wide` (more than one), `:deny` (a Stop or a
+Deny); an option left out is a plain `:answer`, which a parent may always
+pick. A label the options don't have, or an unknown effect, makes the call
+nil (warned), like bad options. Text alone and a dismissal always pass for a
+parent (the worker takes text alone even with `allow_freeform: false`), so
+they must never spend or permit. See
+[Guardrails](guardrails.md#answers-from-a-parent-agent). `effects:` needs a
+chi newer than 0.85.0 (an older one raises on the keyword).
+
 `event[:hook]` is the label the notices carry: `known_names.rb (bundle
 known-names)` for a bundle hook, `audit.rb (config)` for a config hook,
 `turn hook` for one registered at runtime.
@@ -592,7 +608,7 @@ Notes:
 - Ordering: bundle hooks fire by `(priority, bundle_name, hook_name)` (lower priority first), then plain `config.yml` hooks in registration order.
 - Settings: a hook class with `initialize(settings = {})` gets the bundle's section of `config.yml` `bundles:` (see [Settings](#settings)).
 - A bundle can also ship a `plugin.rb` whose `chi.on(event)` blocks are bundle hooks too, next to commands and tools; see [Plugins](plugins.md). There `ctx.notify`, `ctx.steer` and the other `ctx` helpers act as this page's `event[:notify]`… do for the event the block runs for.
-- Shipped bundles (each in a profile: `core` or `dev`, see [Bundle profiles](memory.md#bundle-profiles-core-and-dev)): `chi bundle install guardrails` (rules, see [Guardrails](guardrails.md#the-guardrails-bundle)) and `chi bundle install known-names` (a hook, see [Guardrails](guardrails.md#the-known-names-bundle)), `chi bundle install source-links` (a hook: announces source refs, see [The source-links bundle](#the-source-links-bundle)), `chi bundle install btw` (a plugin: `/btw`, see [Plugins](plugins.md#the-btw-bundle)), `chi bundle install mcp` (a plugin: tools from MCP servers, see [Plugins](plugins.md#the-mcp-bundle)) `chi bundle install loop-guard` (a plugin: breaks tool-call loops, see [Plugins](plugins.md#the-loop-guard-bundle)), `chi bundle install check-in` (a plugin: checks on a long turn, see [Plugins](plugins.md#the-check-in-bundle)), `chi bundle install slow-commands` (a plugin: commands that ran past the execute limit are run as tasks next time, see [Plugins](plugins.md#the-slow-commands-bundle)), `chi bundle install agents-md` (a plugin: a nested AGENTS.md is steered into the conversation on the first touch under its directory, see [Plugins](plugins.md#the-agents-md-bundle)), `chi bundle install cost-cap` (a plugin: a per-session $ cap, `/cap`, see [Plugins](plugins.md#the-cost-cap-bundle)) and `chi bundle install skills` (a plugin: `/skill`, versions of skills, see [Plugins](plugins.md#the-skills-bundle)).
+- Shipped bundles (each in a profile: `core` or `dev`, see [Bundle profiles](memory.md#bundle-profiles-core-and-dev)): `chi bundle install guardrails` (rules, see [Guardrails](guardrails.md#the-guardrails-bundle)) and `chi bundle install known-names` (a hook, see [Guardrails](guardrails.md#the-known-names-bundle)), `chi bundle install source-links` (a hook: announces source refs, see [The source-links bundle](#the-source-links-bundle)), `chi bundle install btw` (a plugin: `/btw`, see [Plugins](plugins.md#the-btw-bundle)), `chi bundle install mcp` (a plugin: tools from MCP servers, see [Plugins](plugins.md#the-mcp-bundle)) `chi bundle install loop-guard` (a plugin: breaks tool-call loops, see [Plugins](plugins.md#the-loop-guard-bundle)), `chi bundle install check-in` (a plugin: checks on a long turn, see [Plugins](plugins.md#the-check-in-bundle)), `chi bundle install slow-commands` (a plugin: commands that ran past the execute limit are run as tasks next time, see [Plugins](plugins.md#the-slow-commands-bundle)), `chi bundle install agents-md` (a plugin: a nested AGENTS.md is steered into the conversation on the first touch under its directory, see [Plugins](plugins.md#the-agents-md-bundle)), `chi bundle install cost-cap` (a plugin: a per-session $ cap, `/cap`, see [Plugins](plugins.md#the-cost-cap-bundle)), `chi bundle install ruby` (a plugin: an RSpec run with no examples at all, a hint, see [Plugins](plugins.md#the-ruby-bundle)) and `chi bundle install skills` (a plugin: `/skill`, versions of skills, see [Plugins](plugins.md#the-skills-bundle)).
 - Installing a bundle executes its hook code at `Engine` startup. Only install bundles you trust, as you would a gem. Hooks are **not** executed at install time (copy-only); they are `module_eval`'d at `Engine.new` inside per-bundle `Samagotchi::Bundles::<name>` namespaces (no top-level `require` collisions). Keep hook files side-effect-free at load time; do work in `#call` — top-level side effects (require, IO, `at_exit`, global assignment) run once per `Engine.new` (class redefinition is idempotent).
 
 Lifecycle:

data/docs/internals/anthropic.md

@@ -97,8 +97,8 @@ index: `message_start` (served model, usage), `content_block_start` (text, think
   back); a `tool_use` input is an object; a thinking block always has a `signature` (`""` when none came).
 - `finish_reason` from `FINISH_REASONS`: `end_turn`/`stop_sequence` → `stop`, `max_tokens` and
   `model_context_window_exceeded` → `length`, `tool_use` → `tool_calls`, `refusal` → `refusal`; anything else as it is.
-- Usage in the OpenAI shape the rest of chi reads (`TokenUsage`, `SessionMetrics`, `ContextStatus`, the web's
-  `ctx.js`): Messages counts `input_tokens` without the cache, so `prompt_tokens` is input + cache reads + cache
+- Usage in the OpenAI shape the rest of chi reads (`TokenUsage`, `SessionMetrics`, `ContextStatus`, and the
+  Bridge's chunk `counts` the web's `ctx.js` reads): Messages counts `input_tokens` without the cache, so `prompt_tokens` is input + cache reads + cache
   writes, with `cached_tokens` and `cache_write_tokens` under `prompt_tokens_details`. Every field is optional and the
   later value wins; all zeros is no usage (`#usage_payload`: Fireworks' `message_start` carries only zeros).
 

data/docs/internals/bundles.md

@@ -22,7 +22,11 @@ user-facing side (what a bundle owns, profiles, needs) is in [memory.md](../memo
 
 | Piece | Role |
 |---|---|
-| `BundleCommand` (`lib/samagotchi/bundle_command.rb`) | `chi bundle install/upgrade/uninstall/status/diff/list/build/trash`; runs the Installer, prints its summary, runs the conflict agent step; refuses a source already installed under another name (`installed_under_another_name?`: a git URL bundle recorded under its repo's name before the manifest named it) |
+| `BundleCommand` (`lib/samagotchi/bundle_command.rb`) | `chi bundle install/upgrade/uninstall/status/diff/list/build/trash/new/test/check`; runs the Installer, prints its summary, runs the conflict agent step; refuses a source already installed under another name (`installed_under_another_name?`: a git URL bundle recorded under its repo's name before the manifest named it) |
+| `BundleCommand::Check` (bundle_command/check.rb) | `chi bundle check [PATH] [--fix] [--set K=V]`: a bundle being written, checked as an install takes it (docs/cli.md lists the codes); parses the manifest from `Shas.parseable` (a placeholder sha is a `sha` finding, not a YAML error), reads the user's installed bundles only for `clash`, and installs and loads through `Testing::Install` in a `Testing::Sandbox` with `force: true`, the log's echoes swallowed |
+| `BundleCommand::Scaffold` (bundle_command/scaffold.rb) | `chi bundle new NAME`: the starting files (block-form `plugin:` entry, `requires_chi` at this chi, a kit test that passes as written); the manifest's shas are filled through `Shas.refresh` |
+| `BundleCommand::TestRun` (bundle_command/test_run.rb) | `chi bundle test`: `RbConfig.ruby -I <chi's lib>` on `test/**/*_test.rb` (Minitest) or `spec/` (RSpec, as `rake bundles:specs`), under `Bundler.with_unbundled_env` when Bundler's runtime is loaded |
+| `Shas` (shas.rb) | a manifest's `sha256:` lines: `.refresh(dir[, text])` rewrites them line by line (the layout kept; a `files:` entry it can't place raises `Shas::Error`), `.stale` → `[Stale(file, old, new)]` (`old` `""` for a placeholder, nil for a plugin / hook / script entry with no sha line), `.parseable` (a placeholder `sha256: sha256:` isn't YAML). Plain Ruby: `rake bundles:sha` / `bundles:check` (`script/release/release_tools.rb`) and `chi bundle check --fix` share it |
 | `SourceNormalizer` (source.rb) | source → local dir; a git/zip/tar extract is *owned* and removed after the install |
 | `SourceIdentity` (source.rb) | what a source is, for comparing two installs of one name: `shipped:<dir>` (any gem or checkout), `git:<url>` (no `#ref`, trailing `/` or `.git`), `path:<realpath>`; nil when it can't place one |
 | `PreparedSource` (source.rb) | one source normalized once (dir, owned, git commit): `BundleCommand` reads the bundle's name from its `manifest.yml` (the name for every kind of source, a git URL too) and hands it to the Installer (`prepared:`), so a source is cloned or extracted once per command |
@@ -47,7 +51,12 @@ and checks the recorded sha256 (and `requires_chi`) before loading.
 The checks live in `Hooks::BundleLoader.load` and `Plugin::Loader.load_bundle`; the loading itself is
 `BundleLoader.load_hook_file` (one hook file, into a given `namespace:`) and `Plugin::Loader.register_file` (one
 plugin file: build, `register`, `commit!`), which raise instead of logging: the bundle test kit
-(`Samagotchi::Testing::Bundle`) loads a bundle's source through them, unchecked.
+(`Samagotchi::Testing::Bundle`) loads a bundle's source through them, unchecked. `Samagotchi::Testing::Install` is the
+checked path in a sandbox: the Installer, then `ExtensionLoad` (bundle hooks, then `load_plugins`), returning the
+Installer's warnings, this bundle's load failures and what it registered (`Install.registered`, also the parity
+spec's shape). A load failure carries `LoadFailures::Failure#location` (the first backtrace frame inside the
+bundle, or a SyntaxError's own line), which `Install` maps from the installed copy (`.bundles/<name>/plugin/`,
+`hooks/`) back to the source dir.
 
 ## Installer#run, in order
 

data/docs/internals/context-telemetry.md

@@ -30,7 +30,8 @@ Emission behavior:
   synthetic char-based estimate (`src=estimate`). The guidance text is dynamic
   and escalates with the bucket: healthy → proceed normally; moderate → prefer
   targeted/range reads; elevated → be concise, avoid large re-reads; critical →
-  summarize aggressively and delegate broad work to subagents. With custom
+  write a short handoff note (state, next step) so the work can go on from it,
+  and delegate broad work to subagents. With custom
   `context.status_thresholds` the top bucket reads critical, the one below it
   elevated, the next moderate, and the first bucket (and the rest below) healthy.
 
@@ -85,6 +86,23 @@ Configuration:
 
 The `context.*` settings are read once, when the turn's `ContextStatus` is built, so a change counts from the next turn.
 
+Per-chunk counts on the SSE stream: the Bridge sends each `generation_chunk` with chi's own `counts`
+(`Bridge::ClientEvent`, from `ContextUsage.normalize` of the provider's payload) instead of the payload, and the
+web's meter (`ctx.js#extractCtxPct`) counts their `total_tokens` against the window (their
+`context_window_tokens` when the server reported one, else `generation_started`'s) or the budget when smaller, as
+`ContextStatus` does. The rules:
+
+- `ctx_pct` is not in `counts`: normalize computes it without the session's LLM context budget.
+- Counts are cumulative for the request and appear only when the server reported any; a missing key means unknown,
+  never 0. Fireworks' all-zero `message_start` gets no usage (`AnthropicAssembly#usage_payload`), and other zeros
+  read as nil (`TokenUsage.first_positive`).
+- `prompt_tokens` includes cached tokens: the Anthropic assembly adds the cache read and write in, and for llama.cpp
+  `TokenUsage.from_payload` reads `tokens_evaluated` (the whole prompt) before `timings.prompt_n` (the uncached part),
+  an order `spec/bridge/client_event_spec.rb` pins on a real fixture.
+- `context_window_tokens` is there only when the payload reported a window (`n_ctx`, `context_window`); llama.cpp's
+  `/completion` chunks don't.
+- A remote host that reports usage only in its last chunk moves the meter at the generation's end, as before.
+
 Context window lookup (`ContextWindow.resolve`, the first that answers wins; the event's `window_source` / the line's
 `window_src` names it):
 

data/docs/internals/engine.md

@@ -478,7 +478,7 @@ Turn events (the main ones; `Events` in `events.rb` keeps the shared sets):
 | `:reminder_injected` | due reminders went into the turn | `{reminders}` |
 | `:context_status` | every request (unless `context.status` is off), the current estimate before it; and outside any turn after `/model` (or when a session is loaded on another model than its last turn ran on), to the observers only (`Engine#announce_switched_context!`) | `{iteration, status, usage, bucket, source}`; the switch's form has no `iteration`: `{usage, bucket, context_window_tokens, context_window_source}`, with `usage.source: "switch"`, and `usage` nil when the new window doesn't resolve (internals/context-telemetry.md) |
 | `:generation_started` | a request begins | `{iteration, context_window_tokens, context_window_source, price, model_ref}` (`price`: the turn's `ModelPrice#to_h`, nil without one; `model_ref`: the turn's model, asked `host:model`, added by the Engine's stream handler from the model `#generate` resolved after the `before_turn` hooks, so a hook's switch is the one named; native adds `profile`, `profile_source`) |
-| `:generation_chunk` | each streamed chunk | `{iteration, content, text, thinking, payload, tool_call?}` |
+| `:generation_chunk` | each streamed chunk | `{iteration, content, text, thinking, payload, tool_call?}` (SSE clients get the Bridge's projection instead: `{iteration, text, thinking, tool_call?, counts?}`, architecture.md) |
 | `:generation_retrying` | the transport retries the request, or the chat loop asks again for a step whose stream dropped mid-answer (`restarted: true`: what the step streamed is void, and the web's live step, the TUI's activity line, the Bridge's TurnAccumulator and the stream hooks' watch start it over) | `{iteration, attempt, max_retries, next_delay, error_class, error_message, status, restarted?}` |
 | `:generation_completed` | a generation ended, or was cut | `{iteration, content_length, thinking_chars, served_model, requested_model, finish_reason, ...}`; a cut adds `stopped_by`, `stop_reason`; the Engine adds `speed`, `tokens`, `model_segments` |
 | `:generation_cancelled` | the turn was cancelled mid-loop | `{iteration, reason, stopped_by}` |

data/docs/memory.md

@@ -317,7 +317,7 @@ profiles, meta bundles that install a set of them:
 | profile | bundles |
 |---|---|
 | `core` | loop-guard, check-in, guardrails, slow-commands, agents-md, cost-cap: the recommended safety set |
-| `dev` | known-names, mcp, btw, skills, source-links, github-pr, coordinator, claude-peer, codex-peer |
+| `dev` | known-names, mcp, btw, skills, source-links, github-pr, coordinator, claude-peer, codex-peer, ruby |
 
 `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

@@ -8,6 +8,9 @@ own.
 This is the first version of the plugin API. More of it comes later: see
 [Not yet](#not-yet).
 
+Writing a bundle? Start with [bundle-authoring.md](bundle-authoring.md): the `chi bundle new` / `test` / `check`
+loop, the event shapes, the kit, the pitfalls.
+
 ## A bundle with a plugin
 
 ```
@@ -742,7 +745,7 @@ full label, `plugin.rb (bundle my-bundle)`.
 | `ctx.prompt_files` | the files whose text is in the session's system prompt now: the AGENTS.md chain (the work tree top down to the cwd) and the appended files (`append_system_prompt:`, `--append-system-prompt`); absolute paths, in prompt order, `[]` before the first build |
 | `ctx.notify(text, level: :info, fallback_for: nil)` | one line to the user, labelled by the bundle (`my-bundle> …`). Every UI shows it, during a turn (a tool, a hook) or between turns (a command). `fallback_for: :display` marks a line that repeats the answer's display (`event[:present]`), which a UI that renders the display leaves out (`fallback_for: :editor`: a file the viewer could open from a ref in its editor): see [Hooks](hooks.md#what-a-hook-can-do-the-runtime). The keyword needs chi 0.35.0 (it raises on an older chi) |
 | `ctx.card(title:, body: "", actions: [], level: :info, id: nil)` | a card in every UI, returning its id: see [Cards](#cards) |
-| `ctx.ask_user(question:, options:, header: nil, allow_freeform: false)` | a single-select question through the question flow: `{selected:, freeform:, selected_indices:}`, or nil (no one to ask, cancelled, bad options) |
+| `ctx.ask_user(question:, options:, header: nil, allow_freeform: false, effects: nil)` | a single-select question through the question flow: `{selected:, freeform:, selected_indices:}`, or nil (no one to ask, cancelled, bad options or effects). `effects:` tags the options a parent agent's answer is held to (label => `:spend`, `:permit`, `:permit_wide` or `:deny`; untagged = `:answer`): tag every option that spends or permits, and never let text alone or a dismissal do either ([hooks.md](hooks.md#what-a-hook-can-do-the-runtime)). It needs a chi newer than 0.85.0 |
 | `ctx.cancelled?` | whether the running turn was cancelled (a long tool should stop) |
 | `ctx.steer(text)` | put text into the running turn: its own user message at the loop's next boundary, shown as `my-bundle> nudged: …`. The model reads it with a header naming your bundle (`[Steer from the my-bundle plugin, mid-task. …]`); the session keeps the raw text. Returns true when queued, false with no turn running (it never starts one; that is `ctx.sessions`' send). Dropped (logged) if the model answers or the turn ends first. Safe from any thread: an anytime command, a hook (false from `:after_turn`), your own |
 | `ctx.stop_turn(reason)` | stop the running turn after a warn notice with the reason; true when it stopped one now. In a `:before_tool_call` block it also denies that call |
@@ -1157,6 +1160,7 @@ bundle.tool("my_tool", path: "a.txt")                    # → the text the mode
 verdict = bundle.tool_call({ name: "execute", content: "rm -rf /" })
 verdict.deny?                                            # a real Guardrails::Verdict (votes: verdict.votes)
 bundle.notices.map(&:text)                               # also cards, steers, stops, generation_stops, questions
+bundle.questions.last.effects                            # an ask_user's tags as given: { "Continue" => :spend }
 bundle.answer({ selected: "yes" })                       # the next ask_user's answer
 bundle.model_answers << "a summary"                      # the next ask_model's answer
 bundle.sessions.on(:children) { |all:| [] }              # ctx.sessions, scripted and recorded
@@ -1205,6 +1209,16 @@ bundle.shutdown
   own sandbox, its bundles shut down after it (chi's shipped bundles keep theirs in `<bundle>/spec/`,
 docs/testing.md). **Minitest:** `require "samagotchi/testing/minitest"` and subclass
   `Samagotchi::Testing::Case` (the same helpers).
+- **Installed, not loaded from source:** `Samagotchi::Testing::Install.run(dir, settings: {})` (or
+  `bundle.install`) installs the bundle into the sandbox as `chi bundle install` does (sha256 and `requires_chi`
+  checked) and loads the installed copy with chi's own loaders. It returns `warnings` (the Installer's),
+  `plugin_failures` / `hook_failures` (each with the `location` in your source, `plugin.rb:12`) and `registered`
+  (commands, tools, hooks per event, inits, toolkits, tool and peer sources). A name chi ships raises
+  `MemoryBundle::Installer::InstallError` unless `force: true`.
+- **From the command line:** `chi bundle test [PATH]` runs a bundle's `test/**/*_test.rb` (or `spec/`) on the
+  Ruby and lib chi runs on, and `chi bundle check [PATH] [--fix]` runs `Install` (and the manifest, sha and
+  `requires_chi` checks) in a sandbox ([cli.md](cli.md#writing-a-bundle-new-test-check)). `chi bundle new NAME`
+  writes a test to start from.
 
 ## The btw bundle
 
@@ -1595,7 +1609,10 @@ bundles:
 - **At the cap** the turn pauses on a question (header "Cost cap"): `Cost cap reached: $3.04 spent of $3.00.
   Continue raises it to $6.00.` with **Continue** (another cap's worth: $3 → $6 → $9, as many steps as it takes to
   pass the spend, saved for the session) and **Stop** (the turn stops, `canceled` with `stopped_by: cost-cap`, and a
-  card shows the spend, reported, estimated and side). With no one to ask (`--non-interactive`) it stops.
+  card shows the spend, reported, estimated and side). With no one to ask (`--non-interactive`) it stops. A parent
+  agent answering it (`chi answer`) may Continue under `guardrails.parent_answers: soft` or `standard`, and only Stop
+  under `hard` (Continue is tagged `:spend`; see [Guardrails](guardrails.md#answers-from-a-parent-agent)). `/cap N` is
+  a command, not an answer: a parent that sends it (`chi send ID -m '/cap 10'`) raises the cap under any strategy.
 - **The cap of a session:** the one `/cap` or a Continue set for it, else its own `cap:` (`chi --set
   cost-cap.cap=3`, `chi send --new --set cost-cap.cap=3`; `--set cost-cap.cap=off`, `0` or a negative number for none), else `child:` for a
   delegate child, else `default:`. Delegates and continued links each have their own cap (a continued link keeps
@@ -2180,6 +2197,46 @@ skill install card) works the same.
   and `VERDICT OK` wakes chi once to close the round. Needs chi 0.67.0 (the closing
   wake: the chi released with this bundle).
 
+## The ruby bundle
+
+`chi bundle install ruby` (or the `dev` profile) installs the bundle shipped
+with chi (`lib/samagotchi/bundles/ruby/plugin.rb`): one `chi.on` hook
+(`:after_tool_call`), and no memory file.
+
+An RSpec run that finds no examples prints `0 examples, 0 failures`, which
+reads green: the model takes the suite as passing and moves on with code no
+test ever loaded. It usually means a path that matched no file, a filter
+(`-e`, `--tag`) that matched no example, or a `.rspec --pattern` that hid
+the specs (a nested project's `.rspec` overrides one). The bundle notices
+that run and steers a hint into the running turn, which the user sees as
+`ruby> nudged: …`:
+
+```
+rspec ran 0 examples: check the path, the filter (-e/--tag) or the .rspec --pattern
+```
+
+It is a nudge for the model, not a denial: the turn goes on, and the model
+can say why the run was empty. It never runs anything.
+
+- **The command.** Only an `execute` counts, and its command must run
+  rspec: one of its simple commands (`&&`, `||`, `;`, `|`, a newline, so
+  after a leading `cd x &&` too) starts with `rspec`, a path ending in
+  `/rspec` (`bin/rspec`, `./bin/rspec`), or `parallel_rspec`, once a leading
+  `X=…` assignment, `bundle exec` and `time` are left out. A command that
+  only names rspec (`grep rspec README`, `echo "bundle exec rspec"`) is not
+  a run.
+- **The output.** Every `<N> examples, <M> failures` line in the execute's
+  output counts (RSpec's summary, with or without `, N pending`), and the
+  hint comes when all of them are 0. `parallel_rspec` prints one per
+  process, so a single process with examples leaves its 0 out of the total.
+- **No summary line, no hint.** A spec that fails to load, a path that
+  doesn't exist, a command killed at its limit: the output already says what
+  is wrong, and the hint would only repeat it.
+
+Nothing is remembered, so the next 0-example run hints again: it can be
+the same mistake on another command, or a different one. A hint the model
+answers before joining the turn is dropped, as any steer is.
+
 ## 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, slow-commands, agents-md, cost-cap, source-links, github-pr, coordinator, claude-peer, codex-peer, and the profiles core and dev) has its own semver in its
+  loop-guard, mcp, skills, slow-commands, agents-md, cost-cap, source-links, github-pr, coordinator, claude-peer, codex-peer, ruby, and the profiles core and dev) has its own semver in its
   `manifest.yml` and, when it needs a newer chi, a `requires_chi:` line. They never upgrade by themselves: users run
   `chi update` (all of them, with the gem) or `chi bundle upgrade NAME`. So:
   - a change to a bundle's files bumps that bundle's `version:`

data/docs/sessions.md

@@ -2,7 +2,7 @@
 
 Sessions are plain files — no DB. Each session is `~/.local/state/samagotchi/sessions/<uuid>.json` (XDG-aware via `XDG_STATE_HOME`) plus a sidecar dir `<uuid>/` with `input/`/`notes/`/`output/`/`owner.lock`/`bridge.json` (`Session.session_dir`), and `tool_output/` once a long `execute` result was cut: its whole output, which the cut result names (`ToolOutputFiles`, the newest 50 kept; see [Tool output guardrails](internals/tool-guardrails.md#the-runners-cut-max_tool_output_chars)). Besides the messages and turn state, the JSON keeps `used_memory_names` (what the session read), `preloaded_memory_names` (`--memory`) and `muted_memory_names` (`--mute`), the last two written before the worker starts so a respawn builds the same prompt, `prompt_notes`, the model notes the system prompt carried at its last build (`[{name, scope, chars, digest}]`, see [Memory](memory.md#model-notes)), `parent_id`, the session that delegated this one (see *Delegating*; `null` otherwise), and `continues`, the session this one continues (the previous link of a chain, see *Session chains*; `null` otherwise); files from before those keys read as empty lists, no parent and no previous link. `model_name` is the resolved model ref (an alias applied, `host:id` when it names a host), so a resumed session keeps its model when an alias is retargeted; `model_typed` is the name it was given as when that differs (an alias), for the `models:` lookup after a resume (`null` otherwise).
 
-**Input files:** a message for a session's worker waits in `input/<timestamp>.json` (`SessionInbox.write_input`: `prompt`, `client_id`, `enqueued_id`, and `images`, `no_interrupt` and `delivery` when they apply; `delivery` is written only for `"queue"`). While a turn runs, the worker merges them at each step boundary in name order, except a queued one or one with images: those wait for the turn's end and run one turn each, in name order, and a file after them still merges (`Worker#pending_input_drain`). A queue is sent only to a worker whose `bridge.json` names the `delivery` feature; an older one would steer it, so `SessionManager.deliver_turn` refuses it (409 `delivery_unavailable`), and any other 4xx the Bridge answers is a refusal too, never a fallback file (except a 413, a body over its size limit: that one still goes in as a file, its `delivery` kept). **Reply files:** a turn that ends with visible text leaves its reply in `output/<timestamp>.txt`, or `output/<timestamp>-<enqueued_id>.txt` when the turn ran an input file with an id (`SessionInbox.write_output`), and the session's `last_turn` keeps that `enqueued_id`; so a wait for one queued message (`chi send --queue --wait`, `ReplyWait`'s `turn:`) finds its own turn's reply or end, never another turn's. The names still sort by time, and every reader takes `*.txt`.
+**Input files:** a message for a session's worker waits in `input/<timestamp>.json` (`SessionInbox.write_input`: `prompt`, `client_id`, `enqueued_id`, and `images`, `no_interrupt` and `delivery` when they apply; `delivery` is written only for `"queue"`). While a turn runs, the worker merges them at each step boundary in name order, except a queued one or one with images: those wait for the turn's end and run one turn each, in name order, and a file after them still merges (`Worker#pending_input_drain`). A queue is sent only to a worker whose `bridge.json` names the `delivery` feature; an older one would steer it, so `SessionManager.deliver_turn` refuses it (409 `delivery_unavailable`), and any other 4xx the Bridge answers is a refusal too, never a fallback file (except a 413, a body over its size limit: that one still goes in as a file, its `delivery` kept). A session command recognized in a file runs without a turn; its completed outcome is kept at `input/settled/<enqueued_id>` so `chi send --wait` ends instead of waiting for a turn that will not run. **Reply files:** a turn that ends with visible text leaves its reply in `output/<timestamp>.txt`, or `output/<timestamp>-<enqueued_id>.txt` when the turn ran an input file with an id (`SessionInbox.write_output`), and the session's `last_turn` keeps that `enqueued_id`; so a wait for one queued message (`chi send --queue --wait`, `ReplyWait`'s `turn:`) finds its own turn's reply or end, never another turn's. The names still sort by time, and every reader takes `*.txt`.
 
 **Removing a queued message:** a message queued for after the running turn (`chi send --queue`, the web's Alt+Enter, `/queue TEXT` in a terminal), or one with images (it waits for the turn's end too), can be taken back while it still waits: the worker's Bridge (`POST /session/:id/turn/dequeue {enqueued_id}`, the `unqueue` feature) deletes its input file and every UI drops it (`:turn_dequeued`). It is a race with the turn's end, decided by the same rename the worker uses to take the file: once a turn took it the answer is `409 already_started` (it runs), and an id the worker no longer knows is `404 unknown_enqueued_id`. A plain message sent without `--queue` is not removable (`409 not_queued`): a running turn's next step may take it at any moment. A wait for its turn (`chi send --queue --wait`, a delegate follow-up's wait) ends at once with `removed` (the tombstone `input/removed/<enqueued_id>` says so), and a `chi -p` run whose queued prompt went ends with exit 1. The `200` carries the removed `prompt`: the web and the attached terminal put it back into the composer to edit (not its images). The images a removed message named stay in the session's `images/`. Not removable: a queued session command (`/queue /model x`: it waits in the worker, not in `input/`), a message in a stopped worker's inbox (the next worker runs it), and the plain REPL's (`--no-shared`) own queue.
 
@@ -27,7 +27,7 @@ A session is deleted if **expired by age OR overflow by count** (unless `keep_st
 
 **A worker outlives whoever started it:** a spawned worker leaves its spawner's process tree (it is forked again, in a session of its own, and reparented to init), so closing the terminal of a `chi web`, or a tool tearing down a background `chi send --wait` and its children, no longer takes the worker and its turn with it.
 
-**A worker killed mid-turn:** while a turn runs, its worker keeps it on disk (`TurnCheckpoint`): the session file has the turn so far (the prompt from the turn's start, then the finished tool steps and lines merged into it) and `interrupted_turn: {id, started_at, at, iteration, enqueued_id}` (`enqueued_id`: the input the turn runs, so any process can tell which turn is running; a continue turn carries its offer turn's), written as the turn starts, at the loop's first iteration boundary and then at most every 10 s (`updated_at` moves with it). The turn's end saves the real messages without the mark. A worker that died without ending its turn (SIGKILL, a crash of the process) leaves the mark, and loses what came after its last written boundary: at most the last 10 s of steps, plus the step in flight. Each checkpoint write also saves the turn's metrics so far to `analytics.json` (tokens, speeds, timings, its finished tool calls), as the record a killed turn leaves: canceled, `cancellation_reason: worker_stopped`; the turn's own end writes over it. The next worker to start for the session (a `chi send`, `--resume`, `--attach`, the web), or a `--no-shared` REPL resuming it, settles the turn before anything else (`TurnCheckpoint.settle`, log `interrupted_turn_settled`): a note `the previous turn was cancelled (worker-stopped) after Ns` goes at the tail, the status goes idle and the mark goes; `last_turn` stays the previous turn's (a new one saved before the turn a `chi send --wait` woke the worker for would end that wait at once). The session shows the turn's prompt and steps with that note; the dead turn is not run again, and the model reads on its next turn that it was cut.
+**A worker killed mid-turn:** while a turn runs, its worker keeps it on disk (`TurnCheckpoint`): the session file has the turn so far (the prompt from the turn's start, then the finished tool steps and lines merged into it) and `interrupted_turn: {id, started_at, at, iteration, enqueued_id}` (`enqueued_id`: the input the turn runs, so any process can tell which turn is running; a continue turn carries its offer turn's), written as the turn starts, at the loop's first iteration boundary and then at most every 10 s (`updated_at` moves with it). The turn's end saves the real messages without the mark. A worker that died without ending its turn (SIGKILL, a crash of the process) leaves the mark, and loses what came after its last written boundary: at most the last 10 s of steps, plus the step in flight. Each checkpoint write also saves the turn's metrics so far to `analytics.json` (tokens, speeds, timings, its finished tool calls), as the record a killed turn leaves: canceled, `cancellation_reason: worker_stopped`; the turn's own end writes over it. The next worker to start for the session (a `chi send`, `--resume`, `--attach`, the web), or a `--no-shared` REPL resuming it, settles the turn before anything else (`TurnCheckpoint.settle`, log `interrupted_turn_settled`): a note `the previous turn was cancelled (worker-stopped) after Ns` goes at the tail, the status goes idle and the mark goes; `last_turn` stays the previous turn's (a new one saved before the turn a `chi send --wait` woke the worker for would end that wait at once); the dead turn's end is recorded under its `enqueued_id` instead, in `<id>/input/settled/<enqueued_id>` (a `last_turn` record: canceled, `cancel_reason: worker_stopped`), which only a wait for that very turn reads (`chi send --queue --wait`, `chi send --wait ID --turn`, a continue's wait): it ends `canceled` with `cancel_reason: worker_stopped`, detail "its worker exited mid-turn", instead of timing out. A reply the turn wrote before its worker died is still its answer. The session shows the turn's prompt and steps with that note; the dead turn is not run again, and the model reads on its next turn that it was cut.
 
 **Stopping a worker:** `chi sessions stop ID` marks the session stopped (an empty `<id>/stopped` file, not a session.json field, which a worker saving at that moment would write over; a resume removes it), sends its worker TERM and waits (up to 10 s) until the worker has let go of `owner.lock`. A running turn is canceled over the Bridge first, with reason `session_stopped` (the turn's line ends "(session stopped)", its note says `cancelled (session-stopped)`, and a command it was running says "stopped as the session was stopped"; a bare signal to the worker makes it "stopped by a signal to chi"; an older worker takes the reason as `manual`); the TERM stops whatever still runs as a Stop with reason `signal` and saves it (a spawned worker traps TERM, HUP and INT: `WorkerSignals`; a turn not ended within 3 s, 0.5 s after a stop or a second signal, is cut and the session saved as it was), and a stopped worker still saves its kept turn, since the marker, not the saved status, says stopped. Any TERM, HUP or INT does the same to a worker outside a stop: it leaves (log `worker stop reason=signal`) and the next send wakes a new one, so a `chi --resume ID` right after spawns a fresh worker. That is also how to restart a worker still running an older chi, which the attached terminal reports when a command or a question dismiss gets a 404, and the web when an answer, a dismiss, a command or a cancel does (`501 not_supported`; `BridgeClient.stale_worker_message`). A command this chi has that the older worker doesn't (`/llm-context`, the web's `llm ctx` chip, against a 0.39.0 worker) says the same, not `not a session command` (`SessionCommands.builtin_name`); a typo keeps its `400 unknown_command`. The web's `POST /api/sessions/:id/stop` waits the same way, for 2 s. A command sent during a turn that waits for its end (`/model X`, `!cmd`; see *Typing during a turn* in [cli.md](cli.md)) and hasn't run when the worker leaves (a stop, a crash) is answered `command_ran {status: "dropped"}`, so no UI keeps showing it waiting.
 
@@ -209,7 +209,7 @@ chi send --new --continues last:3fa2 -m "new day"      # the next link of 3fa2's
 - `--new` prints `<full id>  started` on stdout. With `--wait` that line (and the `sent` line for an existing session) goes to stderr, so stdout is exactly the answer: the reply of the turn the message started, in full. It is the worker's `output/` file, the same one `delegate` reads; a turn that ends with only tool calls and no text has none.
 - `--wait` takes one session: `--new` or one id. A session with a running turn is refused (`busy: a turn is running; wait or attach`, exit 1): the message would merge into it, and its reply would come back as the answer. `--queue --wait` is the way in: the message runs as a turn of its own after the running one, and the wait is for that turn alone (the ack's `enqueued_id` names its reply file and its `last_turn`), so the running turn's reply and end, and a question it asks meanwhile, are not the answer (it keeps waiting through them; its `--timeout` still applies); a question its own turn asks is (exit 3). Two queued waits each get their own turn's answer. A session waiting for an answer is still refused. `--format json` adds `delivery`: `queue`, or `next_step` when the running turn ended before the message went in (it then ran at once, and the answer is still its own).
 - Exit codes with `--wait`: 0 answered; 3 the turn waits for an answer from you (a question, a hook's question, a guardrail approval, or the step-limit question: see [chi as a sub-agent](sub-agent.md#the-step-limit)), and the session keeps waiting: stderr gets the whole question (`waiting for an answer (approval): …`, its text, the numbered options, whether free text is allowed) and how to answer it (`chi answer ID --question QID --option N`, or `chi --attach ID`, the web); 4 `--timeout S` passed with the turn still running (it goes on; wait again); 1 the turn ended without a reply (canceled, failed or empty), the worker failed or vanished, or the session was stopped; 130 on Ctrl-C, which leaves the turn running (`still running: chi --attach ID`). There is no default timeout.
-- `--format json` (with `--wait`) prints one JSON object on stdout however the wait ends, for a script or a parent agent (see [chi as a sub-agent](sub-agent.md)): `{"status":"answered","session_id":…,"text":…}`; `{"status":"question",…,"question":{"id","kind","header","text","options","multi_select","allow_freeform","approval"},"answer_with":"chi answer ID --question QID --option N"}`, where `kind` is `question` (the model's), `hook` or `approval` (with the tool, command, cwd, rule, reason and offered scopes); `{"status":"running",…,"detail":…}` (exit 4, and on Ctrl-C); and `failed`, `canceled`, `removed` (a `--queue --wait` message taken back before it ran), `no_answer`, `error`, `worker_gone` or `stopped` with a `detail` line (exit 1); `failed` adds `error_kind` and `retryable`, `canceled` adds `cancel_reason` and `stopped_by`, when known. A failure before the wait (no such session, a busy one) is `error` too. A usage error (exit 2) prints no JSON.
+- `--format json` (with `--wait`) prints one JSON object on stdout however the wait ends, for a script or a parent agent (see [chi as a sub-agent](sub-agent.md)): `{"status":"answered","session_id":…,"text":…}`; `{"status":"question",…,"question":{"id","kind","header","text","options","multi_select","allow_freeform","approval"},"answer_with":"chi answer ID --question QID --option N"}`, where `kind` is `question` (the model's), `hook` or `approval` (with the tool, command, cwd, rule, reason and offered scopes); `{"status":"running",…,"detail":…}` (exit 4, and on Ctrl-C); and `failed`, `canceled`, `removed` (a `--queue --wait` message taken back before it ran), `no_answer`, `error`, `worker_gone` or `stopped` with a `detail` line (exit 1); `failed` adds `error_kind` and `retryable`, `canceled` adds `cancel_reason` (`worker_stopped`: the turn waited for died with its worker and the next worker settled it) and `stopped_by`, when known. A failure before the wait (no such session, a busy one) is `error` too. A usage error (exit 2) prints no JSON.
 - `--wait ID` with no message (no `-m`, nothing piped) sends nothing: it waits for the session's next reply and prints and exits as above. With a turn running, that turn's reply (its `interrupted_turn` mark names it), not a turn's queued behind it; with the step-limit question standing, the reply of the turn its Continue runs; with an idle session whose last turn already ended, that ended turn is the answer: its reply, or its end when it left no reply — a turn that finished in the gap between waits is reported, not waited for. With none of those (or a worker whose `bridge.json` lacks `turn_ids`), the next reply of any turn. A running session is fine (that is the point), so after exit 3, 4 or 130 an agent waits again this way while the user answers in the web or `chi --attach`; the question pending when it starts doesn't count again. An idle session with no worker waits until something wakes one. With `--new`, or two ids, it is a usage error (exit 2).
 - `--set BUNDLE.KEY=VALUE` (with `--new`, repeatable) gives the new session a bundle setting of its own, as `chi --set` does (see *Bundle settings* below): `chi send --new --set cost-cap.cap=3 -m "…"` starts it with a $3 cap. A bundle or key the installed bundles don't offer is a usage error (exit 2), as is `--set` without `--new`.
 - `--continues ID` (with `--new`) starts the next link of that session's chain instead (see *Session chains*): in its folder, on its model (or the one `--model` names), LLM context, thinking level, toolkit and bundle settings, so `--dir`, `--llm-context*`, `--thinking`, `--toolkit`, `--tool`, `--no-tool` and `--set` are refused beside it; `ID` may be a prefix or `last:ID`, the chain's latest link. Without a message the new link starts idle; `--wait` then has nothing to wait for (a usage error). It prints `<full id>  started (continues 3fa2c1d0)`, with `; 2 delegates moved` inside the parentheses when open delegates moved to it; a refusal (continued already, naming the next link; an open delegate that can't move; a turn running) is `chi send: refused: …`, exit 1, and a `--model` it can't start on is `chi send: could not start a session: …`, exit 1, nothing archived. A fallback to the default model (below) prints `chi send: warning: …`.
@@ -265,11 +265,11 @@ The `delegate` tool hands a task to a **child session**: an ordinary chi session
 - `delegate_result(session:, timeout:)`: waits for a child's next reply: the one named, or the newest running child (`timeout` as for `delegate`: 0 checks once and returns at once). The reply comes back once; a later call waits for the next one. After `wait: false` it isn't needed: the report brings the reply.
 - A wait that timed out or was canceled still gets its delegate report: neither moves the parent's cursor, so the child's reply comes as a report when its turn ends. The result says so (`chi brings its reply here by itself as a delegate report …`; with `queue`, that it joins the next step or turn) and that `delegate_result` waits again only if the turn needs the reply now. A parent that gets no reports (`session.delegate_reports: off`, a `--no-shared` REPL, `--non-interactive`) is told `delegate_result <id> waits again` instead, and `wait: false`'s result says `delegate_result waits for its reply`.
 - What a wait returns, `session: <id>` then `status:` and the text, with the status words `chi send --wait --format json` uses: `answered` with the reply after a `---` line; `question` as soon as the child opens a question (the model's own, or a hook's), with the question's text, options and the `chi answer` command for it (nothing is answered for it: `chi answer`, attach or use the web, then wait again); `failed`, `canceled` or `no_answer` when the child's turn ended with nothing to say (its session shows what happened); `error` (its worker crashed) or `stopped` (`chi sessions stop`) at once; `worker_gone` when the child has had no worker for 15 seconds (it crashed without saying so, or idle-exited): `delegate` with `session:` starts it again; `running` on timeout, or when the parent's own turn is canceled (the child keeps running; the next turn can wait again). A reply saved before the child's worker idle-exited is returned at once.
-- **A child's step-limit question goes back to the parent model**, not to its user: `delegate_result` returns `status: question` with the `chi answer` commands for Continue and Stop, and says the model may instead send a narrower follow-up (`delegate session:`, which drops the question) or report back. A parent's `chi answer` follows `turn.parent_continue` (see [chi as a sub-agent](sub-agent.md#the-step-limit)).
-- **A child at its cost cap** (the [cost-cap bundle](plugins.md#the-cost-cap-bundle), the child's own cap: `child:` in its settings, or `/cap`) asks a `hook` question, "Cost cap": a parent waiting on it (`delegate`, `delegate_result`) gets it back as `status: question` with the `chi answer` commands, `--option Continue` or `--option Stop`. A **background** child (`wait: false`) paused at its cap does not wake its parent: delegate reports skip hook questions (they are the user's, on the child's card) and the approval relay carries approvals only, so the child waits on its card, with the web's bell. The parent sees it at its next `delegate_result`.
+- **A child's step-limit question goes back to the parent model**, not to its user: `delegate_result` returns `status: question` with the `chi answer` commands for Continue and Stop, and says the model may instead send a narrower follow-up (`delegate session:`, which drops the question) or report back. A parent's `chi answer` follows `guardrails.parent_answers` (`hard`: Stop only; see [chi as a sub-agent](sub-agent.md#the-step-limit)).
+- **A child at its cost cap** (the [cost-cap bundle](plugins.md#the-cost-cap-bundle), the child's own cap: `child:` in its settings, or `/cap`) asks a `hook` question, "Cost cap": a parent waiting on it (`delegate`, `delegate_result`) gets it back as `status: question` with the `chi answer` commands, `--option Continue` or `--option Stop` (under `guardrails.parent_answers: hard` a parent's Continue is refused: Stop only). A **background** child (`wait: false`) paused at its cap does not wake its parent: delegate reports skip hook questions (they are the user's, on the child's card) and the approval relay carries approvals only, so the child waits on its card, with the web's bell. The parent sees it at its next `delegate_result`.
 - **A child's approvals go to the parent's user** (the approval relay). While the parent waits (`delegate`, `delegate_result`), a guardrail approval the child opens reopens as the parent session's own approval: the same card in the parent's web page and attached terminal, with the same facts and diff, a line naming the delegate and its task (`delegate ab12 · fix the flaky spec…`, linked to its session) and the header `Approve delegate ab12's tool call?`. The options are the child's, by index; "for the session" says it is the delegate's session (the session scope keys on the child; repo and rule approvals are one shared store). The user answers once there; the parent's model never sees the approval, only one line per relayed approval in the tool's result, before the reply: `approval relayed to your user: execute: git push origin main → allowed once` (or `denied ("why")`, `dismissed (denied)`, `answered on the child`, `not delivered (the child's worker is gone)`, `refused by the child …`, `still open (your turn was stopped)`). The time the card is open doesn't count against `timeout`. While the parent waits on one child, its other running children's approvals are relayed too, oldest first, one card at a time (`+1 more delegate waiting`); each outcome comes in that child's next result.
   - The child's own card stays answerable (the first answer wins: answered there, the parent's card closes as "answered in ab12"). While relayed it says `Waiting for approval in parent ab12: answering here works too`; `chi sessions list` shows the child as `waiting (in parent ab12)` (`--format json`: `relayed_to`), and the web's bell rings for the parent's card, not the child's.
-  - How the child trusts it: the parent's POST that says "answered" (Bridge `POST /session/<child>/relay`) carries no answer. The child asks its parent session's live Bridge (`POST /session/<parent>/relay/status`), which reports only what the parent's question flow took from a UI (`RelayDesk`, in memory only), and takes it only for this child, the question pending now, answered. A parent agent's answer on the relay card (a piped or marked `chi --attach PARENT`, `chi answer`) is held to `guardrails.parent_approvals` by the parent and again by the child.
+  - How the child trusts it: the parent's POST that says "answered" (Bridge `POST /session/<child>/relay`) carries no answer. The child asks its parent session's live Bridge (`POST /session/<parent>/relay/status`), which reports only what the parent's question flow took from a UI (`RelayDesk`, in memory only), and takes it only for this child, the question pending now, answered. A parent agent's answer on the relay card (a piped or marked `chi --attach PARENT`, `chi answer`) is held to `guardrails.parent_answers` by the parent and again by the child.
   - A Stop of the parent's turn closes its card; the child's approval stays open there. A child's worker that goes closes the card (`… worker is gone`); a parent's worker that goes clears the child's "waiting in parent" line within 2 s. A later `delegate_result` relays it again.
   - No relay where the parent can't host one (a `--no-shared` REPL, `--non-interactive`) or isn't waiting (`wait: false` until the next `delegate_result`): the approval waits on the child, with the web's bell, and the result's question block says to deny it or leave it for the user. The model's own questions and hooks' questions come back to the model as before. A grandchild's (a plugin's `ctx.sessions.fork` can make one) is relayed hop by hop: `delegate ab12 → cd34 asks:`.
 - **Delegate reports: a child's reply comes back by itself.** When a child ends a turn that was its parent's (its task, a follow-up, a continue the parent answered, a reminder: not a turn its user typed into it directly), it rings the parent: a small file in the parent's `children/` dir, written after the child's turn is saved. So does a question the parent's model decides (the child's own `ask_user_question`, the step-limit continue; not an approval or a hook's question, which the user answers on the child's card), the turn after such a question whoever starts it, and the child's worker crashing. The parent reads the child as `delegate_result` would and hands its model a **report**: the same text (`session:`, `status:`, the reply), under its own header (`[Delegate report, delivered by chi …; not your user's message. Tell your user what it found …]`), as an input message with `source: "delegate_report"`.

data/docs/sub-agent.md

@@ -59,7 +59,7 @@ Exit codes, both commands:
 | 0 | `not_continued` | (`chi answer`) a Stop answered the step-limit question; the turn's work so far stays |
 | 3 | `question` | chi waits for an answer: `question`, `answer_with` |
 | 4 | `running` | `--timeout` passed; the turn goes on, wait again |
-| 1 | `failed`, `canceled`, `limit`, `removed`, `no_answer`, `error`, `worker_gone`, `stopped` | `detail` says what happened (`limit`: the turn ran out of steps and nobody can be asked, e.g. an older worker; `chi send ID -m '/continue yes'` continues it; `removed`: the `--queue` message waited for was taken back before it ran, no turn ran for it). `failed` adds `error_kind` (the provider error's kind: `credits`, `credits_held`, `rate_limited`, `server`, `auth`, `connection`, …) and `retryable` when known; `canceled` adds `cancel_reason` (`user`: a Stop in the web; `session_stopped`: a session stop, `chi sessions stop` or the web's; `hook`; `ctrl_c`; `manual`) and `stopped_by` (the hook that stopped it, e.g. `loop-guard`) when known |
+| 1 | `failed`, `canceled`, `limit`, `removed`, `no_answer`, `error`, `worker_gone`, `stopped` | `detail` says what happened (`limit`: the turn ran out of steps and nobody can be asked, e.g. an older worker; `chi send ID -m '/continue yes'` continues it, except under `guardrails.parent_answers: hard`, where a parent's `/continue yes` is refused as its `chi answer --option Continue` is; `removed`: the `--queue` message waited for was taken back before it ran, no turn ran for it). `failed` adds `error_kind` (the provider error's kind: `credits`, `credits_held`, `rate_limited`, `server`, `auth`, `connection`, …) and `retryable` when known; `canceled` adds `cancel_reason` (`user`: a Stop in the web; `session_stopped`: a session stop, `chi sessions stop` or the web's; `worker_stopped`: the `--queue` turn waited for died with its worker (detail "its worker exited mid-turn"), settled by the next one; `hook`; `ctrl_c`; `manual`) and `stopped_by` (the hook that stopped it, e.g. `loop-guard`) when known |
 | 2 | (no JSON) | usage error, or an option the question doesn't offer |
 | 130 | `running` | Ctrl-C; the turn goes on |
 
@@ -98,10 +98,11 @@ question and starts a new turn. It can't be dismissed.
 
 A parent may Continue by default: Continue grants no permission (every tool
 call still meets the guardrails), it only spends time and tokens. With
-`turn.parent_continue: false` in chi's config.yml (config.yml only, no
+`guardrails.parent_answers: hard` in chi's config.yml (config.yml only, no
 environment variable) a parent may only Stop: `chi answer` and the worker
-refuse a Continue (exit 1, `a parent agent may only stop this turn here`), and
-the user continues it from the web or the terminal.
+refuse a Continue (exit 1, `a parent agent may only stop this turn here`), the
+question block's command is the Stop, and the user continues it from the web or
+the terminal. See [Guardrails](guardrails.md#answers-from-a-parent-agent).
 
 A chi parent's `delegate_result` gets a child's step-limit question back as a
 `question` with these commands, for its model to decide: continue it (the
@@ -122,23 +123,26 @@ sees only how each was answered. See
 parents (Claude Code, Codex, a script), and for a chi parent that can't host
 the relay (a `--no-shared` REPL, `--non-interactive`).
 
-An approval is a guardrail rule with `verdict: ask`: its user said "ask me". So
-a parent may deny it (`--option Deny --text "why"`, `--text` alone, or
-`--dismiss`) but not allow it: `chi answer` refuses an Allow with exit 1 and
-`allowing a tool call is up to the user: deny it (--option Deny --text WHY),
-and tell your user`. For an approval, the question block and `answer_with` give
-the deny command, not `--option N` or `chi --attach`. The block also offers to
-leave it open: tell your user it waits in chi web (the bell and badge show
-it there), and `chi send --wait --format json --turn <turn_id> ID` waits until
-they answer it. With
-`guardrails.parent_approvals: once` in chi's config.yml (it has no environment
-variable), "Allow once" goes through; the wider scopes never do,
-and neither does any allow on chi's own config, hooks or guardrail rules. See
-[Guardrails](guardrails.md#approvals-from-a-parent-agent).
+An approval is a guardrail rule with `verdict: ask`: its user said "ask me". A
+parent may always deny it (`--option Deny --text "why"`, `--text` alone, or
+`--dismiss`). By default (`guardrails.parent_answers: soft` in chi's
+config.yml, which has no environment variable) it may also give "Allow once";
+the wider scopes never go, and neither does any allow on chi's own config,
+hooks or guardrail rules: `chi answer` refuses those with exit 1 and a line
+like `only Allow once (guardrails.parent_answers: soft) can be given here: deny
+it (--option Deny --text WHY), and tell your user`. With `standard` or `hard`
+no allow goes (`allowing a tool call is up to the user: …`). The question
+block lists what the parent may give: the Allow once command when it may, and
+the deny command (`answer_with` is the deny), never `chi --attach`. The block
+also offers to leave it open: tell your user it waits in chi web (the bell and
+badge show it there), and `chi send --wait --format json --turn <turn_id> ID`
+waits until they answer it. A plugin's question names the options a parent may
+pick when the strategy leaves some out (`allowed_options` in the JSON). See
+[Guardrails](guardrails.md#answers-from-a-parent-agent).
 
 Start a child in the folder it should change (`chi send --new --dir PATH`):
 writes and mutating git outside its own repo ask (`write-outside-repo`,
-`git-outside-repo`), which a parent can only deny.
+`git-outside-repo`), which a parent can at most allow once per call.
 
 An answer typed into `chi --attach` or the REPL counts as a parent's too when
 stdin isn't a terminal or an agent marker (`CLAUDECODE`, `AI_AGENT`,
@@ -208,12 +212,19 @@ Start a task: `chi send --new --wait --format json --timeout 500 -m "<task>"`
   JSON. If you won't answer, add `--dismiss` instead: chi does nothing it asked
   about, finishes with what it found, and the reply comes back (exit 0).
 - `question.kind: approval`: chi wants to run something its user's guardrails
-  flagged, and allowing it is up to your user. Deny it (the `answer_with`
-  command: `--option Deny --text "why"`), and tell your user what it wanted to
-  run and why. Or leave it open: tell your user it waits in chi web (the
-  session's short id), then `chi send --wait --format json --timeout 500 --turn <turn_id> <session_id>`
-  waits until they answer it there. Never allow it yourself, through
-  `chi answer`, a piped `chi --attach` or chi's web API.
+  flagged. What you may give follows chi's `guardrails.parent_answers`, and the
+  question says it: when its `allowed_options` (and the text block's `allow:`
+  line) list "Allow once" (`soft`, the default), you may allow that one call if
+  your task clearly needs it; never a wider scope (this session, a repo, a
+  rule), and never a call on chi's own config, which lists only Deny. Otherwise
+  (`standard`, `hard`, or anything wider) allowing it is up to your user: deny
+  it (the `answer_with` command: `--option Deny --text "why"`), and tell your
+  user what it wanted to run and why. Or leave it open: tell your user it waits
+  in chi web (the session's short id), then
+  `chi send --wait --format json --timeout 500 --turn <turn_id> <session_id>`
+  waits until they answer it there. Never give an answer the question doesn't
+  offer you by another route (a piped `chi --attach`, `chi send -m '/continue
+  yes'`, chi's web API).
 - `status: running` (exit 4): still working. Wait for that same turn again:
   `chi send --wait --format json --timeout 500 --turn <turn_id> <session_id>`.
 - `question.kind: continue`: chi ran out of steps before it answered. If it is

data/docs/testing.md

@@ -47,7 +47,8 @@ Where a composer line goes is decided twice, in Ruby (`ComposerRoute`, both term
 (`composer.js#routeComposerLine`). `spec/fixtures/composer_routes.json` holds the cases both answer: rspec
 (`spec/composer_route_spec.rb`) and `npm test` (`spec/web/public/composer.test.js`) run every row. A change to
 either router adds its row there; a row where a UI differs on purpose (or a found divergence) carries a `web` or
-`repl` override and a `note`.
+`repl` override and a `note`. The Ruby side runs each row with every core command (a new one fails its
+`CORE_ROUTES` check until listed there); a row's names that core lacks stand for plugin commands.
 
 A spec that waits for something uses `wait_until(timeout:)`, or `wait_until!(what, timeout:)` where no check
 follows (stubs, helper threads: it raises "timed out after N s waiting for <what>") — never a loop with no deadline.
@@ -77,7 +78,11 @@ The kit's own specs, in `spec/samagotchi/testing/`, keep it and the bundles hone
   `Testing::Sessions` has `Plugin::Sessions`' methods and parameters, and each `ctx` helper lands in its recorder. A
   member added to the Host fails it until the kit has it.
 - `spec/samagotchi/testing/shipped_bundles_spec.rb`: each shipped bundle with a plugin or hooks registers the same
-  commands, tools, hooks, inits, toolkits and sources loaded by the kit as installed and loaded by chi.
+  commands, tools, hooks, inits, toolkits and sources loaded by the kit as installed and loaded by chi
+  (`Testing::Install`).
+- `spec/samagotchi/bundle_command/check_spec.rb`: `chi bundle check` passes every shipped bundle with no errors (one
+  example per bundle), so a shipped bundle that wouldn't install or load cleanly for a user fails here too. Run it
+  by hand on one with `ruby -Ilib bin/chi bundle check lib/samagotchi/bundles/NAME`.
 - `spec/samagotchi/testing/boundary_spec.rb`, the boundary lint: each bundle's Ruby (plugin, hooks, scripts, specs)
   reaches chi only through `Samagotchi::Testing::Boundary::ALLOWED` (the "Stable for bundles" list) and that
   bundle's `Boundary::EXCEPTIONS` entry, each with why. A new internal reference fails it, and so does an exception

data/lib/samagotchi/answer_command.rb

@@ -6,8 +6,7 @@ require_relative "session_manager"
 require_relative "bridge_client"
 require_relative "reply_wait"
 require_relative "parent_report"
-require_relative "guardrails/parent_approvals"
-require_relative "guardrails/parent_continue"
+require_relative "guardrails/parent_policy"
 require_relative "cli/command"
 require_relative "cli/flags"
 require_relative "cli/parent_wait"
@@ -19,10 +18,10 @@ module Samagotchi
   # how a parent agent running chi as a sub-agent answers; the web and
   # chi --attach answer the same question. See docs/sub-agent.md.
   #
-  # An approval is the user's to allow: a parent may deny it, and allow it
-  # only "once" when guardrails.parent_approvals (config.yml) says so. It is
-  # checked here and again by the worker, which sees the answer marked as
-  # chi answer's. That guards an honest but eager parent, not a boundary:
+  # What a parent may pick is Guardrails::ParentPolicy's: by each option's
+  # effect and this process's config.yml. It is checked here and again by
+  # the worker, which sees the answer marked as chi answer's. That guards
+  # an honest but eager parent, not a boundary:
   # the Bridge and the localhost web take answers from any local process.
   class AnswerCommand
     include CLI::Command
@@ -46,9 +45,11 @@ module Samagotchi
                         about and finishes its reply
         --timeout S     give up waiting after S seconds (exit 4)
         --format json   one JSON object on stdout (see chi send --help)
-        An approval (a guardrail's ask) can be denied here: deny it, and
-        tell your user; allowing it is the user's. With
-        guardrails.parent_approvals: once, "Allow once" is let through.
+        What a parent may pick follows guardrails.parent_answers in
+        chi's config.yml: soft (the default) lets "Allow once" and
+        Continue through, standard Continue but no allow, hard only a
+        deny, a Stop or a plain answer. A wider allow, and any allow on
+        chi's own config, is the user's: deny it, and tell your user.
         A step-limit question (kind continue): --option Continue [--text
         STEER] (the text joins the continued turn as a steer), or
         --option Stop [--text WHY] (exit 0, status not_continued); it
@@ -121,7 +122,7 @@ module Samagotchi
         return failure(not_dismissable(pending)) if options[:dismiss] && ParentReport.continue?(pending)
 
         selected = selection(pending, options) or return @selection_status
-        refusal = approval_refusal(pending, selected, id) || continue_refusal(pending, selected)
+        refusal = parent_refusal(pending, selected)
         return failure(refusal) if refusal
 
         posted = post(id, qid, selected, options)
@@ -158,21 +159,16 @@ module Samagotchi
       labels.uniq
     end
 
-    # Why a parent may not give this answer to an approval, or nil
-    # (Guardrails::ParentApprovals, with this process's config.yml). A
-    # Deny, text alone or a dismissal always passes: each one denies. The
-    # worker checks it again with its own config.
-    def approval_refusal(pending, selected, _id)
+    # Why a parent may not give this answer, or nil (Guardrails::ParentPolicy,
+    # with this process's config.yml and the question's own tags). A deny,
+    # text alone or a dismissal always passes. The worker checks it again
+    # with its own config.
+    def parent_refusal(pending, selected)
       offered = Array(pending.options).map(&:to_s)
       indices = selected.map { |label| offered.index(label) }
-      reason = Guardrails::ParentApprovals.refusal(pending, indices, setting: Guardrails::ParentApprovals.setting)
-      reason && Guardrails::ParentApprovals.message(reason)
-    end
-
-    # Why a parent may not answer Continue (turn.parent_continue: false in
-    # this process's config.yml), or nil; the worker checks it again.
-    def continue_refusal(pending, selected)
-      Guardrails::ParentContinue.refusal(pending, selected) && Guardrails::ParentContinue.message
+      strategy = Guardrails::ParentPolicy.current
+      reason = Guardrails::ParentPolicy.refusal(pending, indices, strategy: strategy)
+      reason && Guardrails::ParentPolicy.message(reason, pending: pending, strategy: strategy)
     end
 
     # A step-limit question can't be left unanswered: the turn waits on it.
@@ -206,8 +202,8 @@ module Samagotchi
 
         not_open(qid)
       when 400 then usage_failure(reply.json&.dig("detail") || "the worker refused the answer")
-      # The worker's own guardrails.parent_approvals refused the allow.
-      when 403 then failure(reply.json&.dig("detail") || "the worker refused the allow: deny it, and tell your user")
+      # The worker's own strategy refused the option (ParentPolicy).
+      when 403 then failure(reply.json&.dig("detail") || "the worker refused that option: deny it, and tell your user")
       when 408 then failure("the worker did not take the answer in time; the question is still open: try again")
       when 404
         return failure(worker_gone(id)) if reply.json&.dig("error") == "unknown_session"