samagotchi 0.85.0 → 0.87.0

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,105 @@ 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`.
+
+#### A session's own level
+
+A session may carry its own `parent_answers`, set when it is created (`chi
+--parent-answers LEVEL`, `chi send --new --parent-answers LEVEL`) and kept by
+its respawns, forks and continues; a `delegate` child starts with its parent's,
+as it is then. It can only tighten: config.yml's value is the ceiling, and the
+stricter of the two applies, in `chi answer`'s check (from the session file),
+the worker's (from its session) and in what the question block offers. A refusal
+then names it: `a parent agent may only stop this turn here (parent_answers:
+hard (this session))`. A looser one is saved as given with a warning
+(`soft is looser than config.yml's guardrails.parent_answers: standard;
+standard applies`) and takes effect only if config.yml is loosened later. A
+value that isn't a level reads as `hard`.
+
+`/parent-answers` shows the level that applies, the session's own and
+config.yml's; `/parent-answers LEVEL` sets the session's own, `/parent-answers
+default` drops it (config.yml's applies). Anyone may tighten it, a parent too
+(`chi send ID -m "/parent-answers hard"`). Loosening it (toward `soft`, or
+`default`) is yours alone: the line must come from you at the REPL, an attached
+terminal or the web composer. chi refuses it (`loosening parent_answers is the
+user's: …`) from `chi send` (a parent's or yours: the worker can't tell them
+apart), from a piped or marked `chi --attach` or REPL, from `chi -p
+--non-interactive`, from a delegate's follow-up and from a plugin; `chi answer`
+has no command route. `--parent-answers` on `--attach`/`--resume` is ignored,
+never sent as the command.
+
+config.yml is read each time an answer is checked; a session's own value stays
+as saved and binds whenever it is the stricter of the two. A session saved as
+`standard` under a `hard` config.yml follows `hard`, and `standard` again once
+config.yml is loosened. A `delegate` child keeps the value it started with,
+whatever its parent changes later.
+
+A parent agent on a real terminal (a PTY: tmux, a kitty window) with no agent
+marker set looks like you, and can loosen it; so can one that edits a session
+file (`<id>.json`, read again by the next worker that wakes for it). That is
+not a security boundary either: config.yml still caps the result.
+
+A setting form waits for a running turn to end, as `/toolkit`'s does: a
+tightening typed while a child's question is pending applies after that turn,
+and a parent may answer the question meanwhile under the level before it.
+
+`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,17 +207,18 @@ 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`.
-
-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).
-
-The guardrails settings (`enabled`, `mode`, `small_models`, `parent_approvals`) are
-read from config.yml only: they have no environment variable, and a worker
+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 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_answers`) are
+read from config.yml only (a session's own `parent_answers` can only tighten it): 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
 which config.yml chi reads, and a worker the parent starts or wakes (`chi
@@ -159,11 +227,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
@@ -177,7 +245,11 @@ person at a terminal with no marker keeps every scope.
 This guards an honest but eager parent, not a hostile one: it is not a
 security boundary. The worker's Bridge and the web's answer route on localhost
 take an answer from any local process, which can leave the marker out (or
-post through the web) and get every scope. chi's instructions for parents ([chi as a
+post through the web) and get every scope. In the same way a parent can
+loosen a session's own level by posting `/parent-answers` with a forged
+`tui:<pid>` or `web:<tab>` client id to the Bridge or the web's command route,
+by editing the session file, or by running `chi --attach` on a PTY with the
+markers cleared. chi's instructions for parents ([chi as a
 sub-agent](sub-agent.md)) tell them to use `chi answer` only.
 
 ## Protected paths
@@ -511,7 +583,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

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` (or the session's own, stricter one) 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` (config.yml's, or the session's own when stricter) (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,10 +209,11 @@ 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: …`.
+- `--parent-answers LEVEL` (with `--new`) gives the new session its own `guardrails.parent_answers` (`hard`, `standard`, `soft`), tighten-only: config.yml's applies when it is stricter, with `chi send: warning: --parent-answers soft is looser than config.yml's …`. See *Parent answers* below.
+- `--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, bundle settings and parent answers, so `--dir`, `--llm-context*`, `--thinking`, `--toolkit`, `--tool`, `--no-tool`, `--set` and `--parent-answers` 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: …`.
 - The 16 KiB cap applies: `git diff | chi send --new …` on a big diff is refused; name the branch in the message instead and let the session read it.
 - A session nobody attaches to stalls at its first question or guardrail ask until someone answers it (`chi answer`, the web, `chi --attach`), and its worker stays up meanwhile: it doesn't idle-exit while a question waits (`chi sessions list` shows it as `waiting`; `chi sessions stop ID` frees it). Otherwise it idle-exits after `session.idle_exit_minutes` like any worker. These are ordinary sessions: delete them like any other.
 
@@ -246,6 +247,17 @@ declares every tool (full). The file stores only the name: a kit's tools and pro
 `/toolkit` changes it, saved at once, from the next turn's start. See
 [Toolkits](configuration.md#toolkits).
 
+## Parent answers
+
+A session file's `parent_answers` (`hard`, `standard`, `soft`, or `null` for none) is the session's own
+`guardrails.parent_answers`: what a parent agent (`chi answer`, a relayed answer, a piped or marked attach) may
+answer on its questions. It may only tighten config.yml's: the stricter of the two applies, in the worker's check and
+in `chi answer`'s, and in what `chi send --wait`, `delegate_result` and the delegate reports tell a parent it may pick.
+It is set at creation (`chi --parent-answers`, `chi send --new --parent-answers`); a respawned worker, a continue and a
+fork keep it, and a `delegate` child starts with its parent's as it is then (a later change on the parent doesn't reach
+it). A value that isn't a level reads as `hard`. `/parent-answers` changes it; loosening it is yours alone (see
+[Guardrails](guardrails.md#answers-from-a-parent-agent)).
+
 ## Bundle settings
 
 A session file's `bundle_settings` (`{"cost-cap": {"cap": 3}}`, `{}` for none and for a session from before them)
@@ -265,11 +277,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`, or the child's own when stricter (`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`, config.yml's or the child's own, 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` (each session's own, when stricter) 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"`.