samagotchi 0.87.0 → 0.89.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1bfd7070b1c55cbb0e0647a79ec729996a78318ca2b2f4ccbf19c24ce7240eb9
-  data.tar.gz: 5fa4d754f3c9bb79767978d3b9fa6ac1c7091c84897a9043f3ad3129bd98c24c
+  metadata.gz: f7e58a54e40f49c1617636172def63d9e6a3eaa3384ac33e26c0b55c75332555
+  data.tar.gz: 063a36d57a613a117e62b2882883c22e1ce413044c1e6d18e66aa1c8af0d6d83
 SHA512:
-  metadata.gz: 787b7debd71f8a408ffaa801bd7d352de1f3769d018959b35e3933b16641efb194220630482d14f5ec32d4c50b5fce8f56c8a78b88a1fc1c2de58c2e05e6b361
-  data.tar.gz: 5f3759bd7c6e1e9fea4e5b7af8eab1c107d5296f9eba85b0b99fd42381c5a1c3dbb01b7efb86b52ec14b11958333110a97cfab80b5d8fd5a3a1489cab2f50bdd
+  metadata.gz: 879572f97fd05fdff6f15d4c91c3f3ce30d480ff0022b1ad3fb0220423c124004c67908f97e85ad6309302720671938cc90da80c6315de0134c9240a9b477feb
+  data.tar.gz: 0faf651033f823e4eadc87926d4c370e3e8eb714a4f8106d735110bfe7c8517972a70a4e960448ccda3b8ac1679c796e93b587070255803eb57e24e8c984a2b1

data/CHANGELOG.md

@@ -8,6 +8,38 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.89.0] - 2026-10-19
+
+### Added
+
+- `chi bundle try PATH -p TEXT` runs one real model turn in an isolated sandbox with the bundle and shipped
+  `guardrails` installed and a $1 cost cap; `--json` exposes an experimental machine-readable trace.
+- `chi bundle install --dev PATH` installs a bundle you are writing as a link to its folder: edits to its plugin,
+  hooks, rules and scripts apply at the next session with no re-install, and their sha256 isn't checked (that
+  bundle only). Memories are copied; re-install with `--force` to pick up memory edits. A re-install from the same
+  PATH prunes dropped hooks. It refuses chi-shipped bundles and profiles and warns when a linked script needs
+  `chmod +x`. `upgrade` refuses it; `uninstall` never touches PATH. `chi bundle status` shows `dev → PATH (missing)`
+  if the source is gone.
+
+### Changed
+
+- minitest is now a dependency of the gem, so `chi bundle test` runs a bundle's Minitest tests (and the one
+  `chi bundle new` writes) on a slim or vendored install without `gem install minitest`.
+
+## [0.88.0] - 2026-10-19
+
+### Added
+
+- A `delegate` child's hook question (the cost cap's Continue/Stop, a bundle's `ctx.ask_user`) now reaches its parent,
+  in the background too: reported to the parent's model when it may pick something other than a deny under the
+  child's `parent_answers` (so under the default `soft` a background parent may Continue its child's cost cap), else
+  relayed to the parent's user as a card, as approvals are.
+
+### Fixed
+
+- A session file whose `parent_answers` isn't `hard`, `standard` or `soft` (a hand edit) now gets one warning when
+  its worker loads it, instead of being read as `hard` silently.
+
 ## [0.87.0] - 2026-10-19
 
 ### Added
@@ -3481,7 +3513,9 @@ and long-lived sessions.
 - A macOS desktop helper (`chi desktop install`): a "Send to chi" Service and a
   hotkey panel that send selected text or the clipboard to your sessions.
 
-[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.87.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.89.0...HEAD
+[0.89.0]: https://github.com/dm1try/samagotchi/compare/v0.88.0...v0.89.0
+[0.88.0]: https://github.com/dm1try/samagotchi/compare/v0.87.0...v0.88.0
 [0.87.0]: https://github.com/dm1try/samagotchi/compare/v0.86.0...v0.87.0
 [0.86.0]: https://github.com/dm1try/samagotchi/compare/v0.85.0...v0.86.0
 [0.85.0]: https://github.com/dm1try/samagotchi/compare/v0.84.0...v0.85.0

data/docs/bundle-authoring.md

@@ -11,14 +11,33 @@ chi bundle new my-bundle     # ./my-bundle: manifest.yml, plugin.rb, test/my_bun
 cd my-bundle                 # edit plugin.rb and the test
 chi bundle test              # the tests, on chi's own Ruby and lib (exit status: the tests')
 chi bundle check --fix       # manifest, files, shas (--fix rewrites them), requires_chi, install + load in a sandbox
+chi bundle try . -p "Say hello"  # one real model turn; trace the bundle in an isolated install sandbox
 chi bundle install .         # into the user's chi; a NEW session loads it (a running one doesn't)
+chi bundle install --dev .   # or as a link to this folder: edits apply at the next session, no re-install
 ```
 
+While you write it, `install --dev .` (once; `uninstall NAME` leaves dev mode) then try it in chi: a new session
+loads the plugin and hooks from the folder as they are, with no sha check (that bundle only; memories are copied).
+Re-install with `--force` from the same PATH to pick up memory edits.
+Dev-linked scripts aren't chmodded, since that would change the source. Chi warns with a `chmod +x PATH/scripts/x`
+hint when a listed script isn't executable; set that bit on the source script.
+
 `check` prints one finding per line, `error|warn|info CODE file[:line]: message (fix: hint)`, and exits 1 on any
 error. Run it after every edit: an install takes exactly what it checks. It installs into a temp sandbox, not
 the user's config or state, but `check` and `test` run the bundle's plugin and hooks in their own process, as
 written: run them on code you'd install.
 
+## Trying a bundle
+
+After `chi bundle check --fix`, run `chi bundle try . -p "Say hello"` for one real model call using the user's
+configured hosts and keys. It installs the bundle plus chi's shipped guardrails and a default $1 cost cap, then
+prints tool calls, hook notices, cards, questions, the answer, token totals and cost.
+
+The child uses a temporary config, state and working directory; the user's other bundles and memories aren't loaded,
+nor are the current project's `AGENTS.md` / `CLAUDE.md` files. This is not a security sandbox: the bundle and tools
+run with the user's real HOME and account, and can access files and services available there. Use `try` only with
+code you trust. See [CLI: Trying a bundle](cli.md#trying-a-bundle) for flags, `--json`, `--keep` and exit statuses.
+
 ## The files
 
 ```yaml

data/docs/cli.md

@@ -26,6 +26,9 @@
 - `chi update [--dry-run] [--no-gem] [--no-bundles] [--no-desktop]` — update an installed chi: the gem, the system bundle, the shipped bundles you installed and the desktop helper, in one table (see [Updating](#updating))
 - `chi bundle install|upgrade|uninstall|status|diff|list|build|trash|new|test|check` — manage memory bundles (see [Bundle hooks](hooks.md#bundle-hooks-unified-workflow-bundle)); `list` shows the installed ones and the ones shipped with chi, which `install <name>` installs; `core` and `dev` are profiles that install a set of them (see [Bundle profiles](memory.md#bundle-profiles-core-and-dev),  [Guardrails](guardrails.md), [Plugins](plugins.md#the-btw-bundle), [the mcp bundle](plugins.md#the-mcp-bundle) [the loop-guard bundle](plugins.md#the-loop-guard-bundle), [the check-in bundle](plugins.md#the-check-in-bundle) and [the skills bundle](plugins.md#the-skills-bundle)). `trash` lists and empties the bundle trash (moved files from uninstalls/upgrades). A usage error (an unknown subcommand or flag, a missing argument, a bad `build --scope`) exits 2, as for the other subcommands. Plain `chi` and `chi web` exit 1 on an unknown flag, a flag missing its value or a stray argument. `new`, `test` and `check` are for writing one: see [Writing a bundle](#writing-a-bundle-new-test-check)
 
+- `chi bundle try PATH -p TEXT [options]` — install a bundle in a temporary, filtered sandbox, run one real model turn,
+  and print its trace (see [Trying a bundle](#trying-a-bundle)).
+
 ### First setup
 
 `chi bootstrap TARGET` names the model server and writes the config for it:
@@ -100,8 +103,16 @@ The loop for a bundle you're writing (the whole path: [bundle-authoring.md](bund
   Bundler env: `test/**/*_test.rb` on Minitest (`-r samagotchi/testing/minitest`), or else `spec/` on RSpec with
   the kit (`--options /dev/null -r samagotchi/testing/rspec`, as `rake bundles:specs`). `ARGS` go to the runner
   (`-- -n /name/`). Exit status: the tests'; 1 with no tests; 2 for usage, or when minitest / rspec doesn't load on
-  chi's Ruby. The tests run the bundle's code as written, with your environment (the kit sandboxes each
-  test's HOME and XDG dirs, not the process).
+  chi's Ruby (minitest is one of chi's gems; rspec is optional). The tests run the bundle's code as written, with
+  your environment (the kit sandboxes each test's HOME and XDG dirs, not the process).
+- `chi bundle install --dev PATH` installs the bundle in the local directory `PATH` (not a git URL, archive or name:
+  exit 2) as a link to it: its plugin, hooks, rules and scripts are `PATH`'s own files, so an edit applies at the
+  next worker or `chi web` restart with no re-install, and their sha256 isn't checked, for this bundle only (the
+  record says `dev`; every other bundle is checked as before). Its memories are copied at install. `chi bundle
+  status` shows `NAME vX dev → /abs/path`. `chi bundle upgrade NAME` refuses it (it follows its source already; to
+  leave dev mode: `chi bundle uninstall NAME`, then `chi bundle install` without `--dev`), as does a plain install
+  over it, and `--dev` over a normal install. `uninstall` removes the links and the record, never `PATH`'s files.
+  `check PATH` and `test PATH` are unchanged.
 - `chi bundle check [PATH] [--fix] [--set KEY=VALUE]` (PATH defaults to `.`) checks it as an install takes it, one
   finding per line, `error|warn|info CODE file[:line]: message (fix: hint)`, then `ok|failed: N errors, N
   warnings`. Exit 1 on any error, 0 otherwise, 2 for usage. It installs and loads the bundle in a temp sandbox
@@ -120,6 +131,34 @@ The loop for a bundle you're writing (the whole path: [bundle-authoring.md](bund
   exceptions aside) and `tests` (info: how to run them, or "no tests"). `--set KEY=VALUE` (repeatable, typed as
   `chi --set`) goes to `bundles: <name>:` in the sandbox's config.yml.
 
+### Trying a bundle
+
+`chi bundle try PATH -p TEXT [--model NAME] [--memory NAME] [--mute NAME] [--toolkit NAME] [--thinking LEVEL]
+[--set KEY=VALUE] [--json] [--keep] [--timeout SECONDS]` installs and runs the bundle in a temporary config, state
+and work directory, then prints a trace of tool calls, notices, questions, the answer, token totals and cost. The
+child's working directory is outside your repository, so project memories and `AGENTS.md` / `CLAUDE.md` files in
+your current directory aren't loaded. Your hosts, API-key environment variables, Keychain and other runtime
+settings are retained, but your configured bundles, hooks, guardrails, memories, appended system prompts and
+attached context sources are not copied. Chi installs its shipped `guardrails` and `cost-cap` bundles for the run;
+the default cap is $1 and `--set cost-cap.cap=N` changes it. Other `--set KEY=VALUE` entries are typed config
+values under `bundles: <tried-bundle>:`; unlike `chi --set BUNDLE.KEY=VALUE`, they are not session settings and
+aren't checked against `session_settings:`. `--memory` and `--mute` accept comma-separated names and repeat.
+`--timeout` defaults to 300 seconds. An ask that no one can answer or a guardrail denial is traced and warned
+about without changing the child's exit status; hook questions made with `ctx.ask_user` are invisible in
+non-interactive mode. `--keep` retains the temporary sandbox and prints its path and debug log. `--json` writes
+one experimental JSON object to stdout and human trace lines to stderr; its keys are `session_id`, `exit_code`,
+`answer`, `tools` (`index`, `name`, `args`, `status`, `duration_ms`), `notices`, `cards`, `questions`,
+`interactive_blocked`, `used_memories`, `tokens` (`prompt`, `completion`), `cost`, `cost_is_estimate`, `model`,
+`sandbox`, `denied` (1-based tool indexes) and `stderr_tail` (last 4,000 characters). Exit status: 2 for usage,
+1 for install/turn failure or timeout, 130 for Ctrl-C, otherwise the child's status.
+
+`try` runs the bundle's code and the model's tools with your real HOME, account and keys. Its temporary working
+directory and filtered config do not make untrusted code safe: a plugin, hook or model tool can still access files
+and services available to your account. Use it only for code you trust.
+
+Tool arguments are capped to 60 characters in the text trace and 200 in JSON; the text trace shows at most 10 answer
+lines, while JSON includes the full answer. Either may contain secrets.
+
 ### Listing the models
 
 `chi models` asks every host in `hosts:` for its models, in parallel, and prints the names `--model` (and
@@ -491,9 +530,9 @@ file and index line stay as they are; only this session doesn't see it.
 - Names are checked before the launch, warnings only: `Warning: --memory 'x'
   not found`, `Warning: --mute 'x' matches no memory`, `Warning: 'x' is both
   --memory and --mute; muted`.
-- `--attach ID` or `--resume ID` with either flag: the session's prompt is
-  already built, so the flags are ignored with one line,
-  `(--mute applies to a new session; <id>'s prompt is already built)`.
+- `--attach ID` or `--resume ID` with either flag: the session keeps its
+  own, so the flags are ignored with one line,
+  `(--mute applies to a new session; <id> keeps its own)`.
 - The status row shows `mem: <used and preloaded>` and `muted: <names>`; the
   Web UI's info-bar tooltip shows `memories: … · preloaded: … · muted: …`.
 - The `read` tool on `memories/<name>.md` is not refused (a guardrails rule

data/docs/guardrails.md

@@ -103,7 +103,12 @@ The file tools can't write the store.
 ### Answers from a parent agent
 
 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
+go to the user on the parent's own card (the approval relay), as do the hook
+questions (the cost cap's Continue/Stop, a bundle's `ctx.ask_user`) where the
+parent may pick nothing but a deny under the child's `parent_answers`; the
+others come back to the parent's model with the block below. A dismissal
+always passes (the hook decides what no answer means): the strategy is a
+convention for an honest parent, not a barrier. 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

data/docs/internals/bundles.md

@@ -24,6 +24,7 @@ user-facing side (what a bundle owns, profiles, needs) is in [memory.md](../memo
 |---|---|
 | `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::Try` (`bundle_command/try/`) | `chi bundle try PATH -p TEXT`: filtered-config `Sandbox` installs the tried bundle and shipped `guardrails` / `cost-cap` in a separate child, then `Run` starts one non-interactive chi process from its realpath work dir; `TraceReader` reads that session's analytics, cards and session JSON by id (never `Session.list`), joining timing and tool args for text or experimental JSON output. `Sandbox#child_env` is a Hash, never an ENV mutation; it keeps ordinary user model settings and Keychain access while dropping the spawner's session/guardrail/worker markers. |
 | `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 |
@@ -45,6 +46,15 @@ user-facing side (what a bundle owns, profiles, needs) is in [memory.md](../memo
 | `IndexSize` | one scope's memory index as the prompt carries it (tokens, lines, bytes): `memory.index_warn_tokens`' crossing note after a memory write, `chi self`'s summary, the prompt's figures (`SystemPrompt`) |
 | `Placeholder` | `{{placeholder}}` patterns left in an installed memory, one line per file from `Installer#detect_placeholders`; a hint, never a gate |
 
+A dev install (`chi bundle install --dev PATH`, `Installer#initialize(dev: true)`) links instead of copying:
+`AssetInstaller#place` symlinks each hook, rule file, plugin and script into `.bundles/<name>/` to its realpath in
+the source (memories are still copied: their bases and the index are the install's), and the record gets `"dev": true`
+(`InstalledBundle#dev`, `source` the realpath) with `Provenance::DEV_SHA` (`sha256:dev`, never a hex digest) in
+place of every hook, rule, plugin and script sha256. `Provenance.sha_matches?` / `.unchecked?` read it as "not
+checked", which is how the readers below skip it for that bundle only. `Installer#refuse_dev_mismatch` keeps a dev
+and a normal install from replacing each other (this is also why `chi bundle upgrade` refuses a dev bundle);
+`Uninstaller` removes links with `rm_rf`/`rm_f`, which never follow them into the source.
+
 Readers of the installed state: `Hooks::BundleLoader` (Engine), `GuardrailWiring#bundle_rules`, `Plugin::Loader`,
 `ContextProviders` (scripts), `BundleNeeds` (index markers). Each goes through `Provenance.each_installed` / `#record`
 and checks the recorded sha256 (and `requires_chi`) before loading.

data/docs/sessions.md

@@ -278,13 +278,13 @@ The `delegate` tool hands a task to a **child session**: an ordinary chi session
 - 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 `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.
+- **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", `Continue` or `Stop`. Like every hook's question on a `delegate` child, it goes where it can be decided, under the child's `guardrails.parent_answers` (config.yml's, or the child's own when stricter): when the parent may pick an option other than a deny (Stop) there, `standard` and `soft` here, it comes back to the parent's model as `status: question` with the `chi answer` commands; when it may not, `hard` here (a parent's Continue is refused), it goes to the parent's user as a card, as approvals do (the relay below), and the model sees one line: `hook question relayed to your user: Cost cap → Stop` (or `dismissed`, which the hook reads as it likes, cost-cap as Stop; `refused by the child …`, `answered on the child`, `still open (your turn was stopped)`). Free text alone doesn't count as an option the parent may pick. A **background** child (`wait: false`) paused at its cap rings its parent as a question does (delegate reports, below): the parent's model gets it as a report when it may answer; otherwise the parent's worker relays it to its user at its next step boundary, or in a wake turn's first boundary when idle (before the model is called), and the report the model gets is the outcome line. While that card is open the parent's turn waits on it; a Stop closes it and leaves the question for your next input (or a `delegate_result`): no wake turn offers that question again meanwhile, while other children's reports and attached-context wakes go on. Under the default `soft` that means a background parent's model now hears its child's cost cap, and may Continue it.
+- **A child's approvals go to the parent's user** (the approval relay), and so do the hook questions its parent can't usefully answer (above: a card headed `delegate ab12 asks: Cost cap`, the child's options and kind, no approval facts). 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_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"`.
+  - No relay where the parent can't host one (a `--no-shared` REPL, `--non-interactive`) or, for an approval, isn't waiting (`wait: false` until the next `delegate_result`; a hook's question it may only deny is relayed from a delegate report instead, above): 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 the hooks' questions the parent may answer, come back to the model as before. A hook's question already answered on one of the parent's relay cards (a refused answer: it waits for the user on the child) is not relayed again; one whose card closed (a Stop, the child gone) is, and an approval always is, 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 decides (the child's own `ask_user_question`, the step-limit continue, a hook's question, relayed to the parent's user first when the parent may only deny it; not an approval, which the relay or the user on the child's card answers, nor a card the child relays from its own child), 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"`.
   - Parent mid-turn: the report joins the turn at its next iteration boundary (a "delegate report" bubble in the web, `delegate report> ab12cd34 answered: …` in the attached terminal).
   - Parent idle: it runs a turn for the report (a *wake turn*, `last_turn.origin: "delegate_report"`) within the worker's 5 s tick, or wakes a worker for it when the parent's has idle-exited. Several reports that wait together are one turn and one message. A stopped, archived or scratch parent, or one open in a `--no-shared` REPL, is not woken: the rings wait on disk and join the next turn it runs (the user's message first). An archived parent that a later link continues wakes that link instead, which takes the rings its moved delegates left there (see *Session chains*). A worker just started (`chi send` to a stopped parent) runs no wake turn in its first 2 s, so the message it was started for goes first.
   - The parent's cursor per child (the newest reply it was given and the child as it was then) is in its `delegates.json`, shared with `delegate_result` and `wait: true`: a reply the model already had is never reported again, also after the parent's worker restarts. A ring is deleted only when the turn that took its report stays in the conversation (completed, canceled, or failed but kept: one that got to tool steps, or a reminder or continue turn, which keep what they read); a turn rolled back (a failed one that got nowhere, a canceled continue turn) leaves it for the next one (and the report isn't handed back to the composer). So the model reads each report once, unless a later `!rollback` erases a kept turn (what it read goes with it).

data/docs/sub-agent.md

@@ -13,6 +13,15 @@ worker keeps the turn paused. The parent answers with `chi answer`, from what it
 knows or after asking its own user, and chi goes on from there. The model gets
 the answer as its tool result, as if you had answered in the web.
 
+A chi parent's own `delegate` children work the same way, with one shortcut:
+their approvals, and the hook questions the parent may only deny under the
+child's `guardrails.parent_answers`, go to the parent's user as a card in the
+parent's UIs instead (the relay, [Sessions](sessions.md#delegating)). When an
+agent runs that parent with `chi send --wait`, the relay card is the parent's
+own question: exit 3 with its text (`delegate ab12 … asks:`), options and
+`answer_with`; the JSON has no `relay` key. Its `chi answer` is held to the
+parent's setting, then to the child's.
+
 The other direction, chi sending a part of its work to a Claude Code session
 you already work with (to validate, as context, or with a question), is the
 [claude-peer bundle](plugins.md#the-claude-peer-bundle): Claude pairs with the

data/lib/samagotchi/bundle_command/test_run.rb

@@ -10,7 +10,7 @@ module Samagotchi
     # *_test.rb runs on Minitest with the kit's Case; a spec/ with no test/
     # on RSpec with the kit's helpers, as `rake bundles:specs` runs the
     # shipped ones. Outside any Bundler env (Bundler.with_unbundled_env, as
-    # SessionManager's unbundled_env_changes): chi's gems don't include minitest.
+    # InstalledGem.unbundled_env_changes), where chi's own gem dependency minitest loads.
     # When the framework loads only inside the Bundler env chi itself runs in
     # (a checkout or a vendored install: its gems in vendor/bundle), there.
     # The tests' exit status is #run's.
@@ -37,7 +37,7 @@ module Samagotchi
       private
 
       def minitest(tests)
-        return missing("minitest", "gem install minitest") unless loads?("minitest")
+        return missing("minitest", "it ships with chi: reinstall chi (gem install samagotchi)") unless loads?("minitest")
 
         requires = tests.map { |file| "require #{file.inspect}" }.join("; ")
         say("#{tests.size} test file#{"s" unless tests.size == 1}")

data/lib/samagotchi/bundle_command/try/run.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "open3"
+require "rbconfig"
+
+module Samagotchi
+  class BundleCommand
+    module Try
+      class Run
+        Result = Data.define(:exit_status, :stdout, :stderr, :session_id, :timed_out)
+        INTERRUPT_GRACE = 5
+        READER_GRACE = 2
+        GROUP_TERM_GRACE = 0.1
+        POLL_INTERVAL = 0.05
+
+        def initialize(sandbox)
+          @sandbox = sandbox
+        end
+
+        def run(prompt:, options:, timeout:)
+          command = [RbConfig.ruby, "-I", Sandbox::LIB_DIR, Sandbox::CHI,
+                     "--no-shared", "--non-interactive", "-p", prompt, *child_options(options)]
+          trap_state, old_traps = trap_forwarding
+          pid = nil
+          streams = []
+          readers = []
+          begin
+            Open3.popen3(@sandbox.child_env, *command, chdir: @sandbox.work_dir, pgroup: true, in: File::NULL) do |stdin, stdout, stderr, wait|
+              pid = wait.pid
+              streams = [stdout, stderr]
+              stdin.close
+              readers = streams.map { |stream| Thread.new { read_stream(stream) } }
+              attach_child(trap_state, pid)
+              timed_out = false
+              status = wait_for(wait, timeout)
+              if status == :timeout
+                timed_out = true
+                signal_group(pid, "INT")
+                status = wait_for(wait, INTERRUPT_GRACE)
+                if status == :timeout
+                  terminate_group(pid)
+                  status = wait.value
+                end
+              end
+              out, err = finish_readers(readers, streams)
+              code = timed_out ? CLI::Exit::FAILED : process_exit_status(status)
+              Result.new(exit_status: code, stdout: out, stderr: err, session_id: err[/^Session: (\S+)/, 1],
+                         timed_out: timed_out)
+            end
+          rescue SystemCallError => e
+            raise Sandbox::Error, "chi bundle try: couldn't run chi: #{e.message}"
+          ensure
+            terminate_group(pid) if pid
+            close_streams(streams)
+            stop_readers(readers)
+            restore_traps(old_traps)
+          end
+        end
+
+        private
+
+        def child_options(options)
+          args = []
+          %i[model toolkit thinking].each do |key|
+            args.concat(["--#{key}", options[key]]) if options[key]
+          end
+          %i[memory mute].each do |key|
+            Array(options[key]).each { |value| args.concat(["--#{key}", value]) }
+          end
+          args
+        end
+
+        def wait_for(wait, seconds)
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds
+          loop do
+            return wait.value if wait.join(POLL_INTERVAL)
+            return :timeout if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+          end
+        end
+
+        def trap_forwarding
+          state = { pid: nil, pending: nil }
+          old = {}
+          %w[INT TERM].each do |signal|
+            old[signal] = Signal.trap(signal) do
+              if state[:pid]
+                signal_group(state[:pid], signal)
+              else
+                state[:pending] ||= signal
+              end
+            end
+          end
+          [state, old]
+        end
+
+        def attach_child(state, pid)
+          state[:pid] = pid
+          pending = state[:pending]
+          state[:pending] = nil
+          signal_group(pid, pending) if pending
+        end
+
+        def restore_traps(old)
+          old.each { |signal, handler| Signal.trap(signal, handler) }
+        end
+
+        def signal_group(pid, signal)
+          Process.kill(signal, -pid)
+        rescue Errno::ESRCH
+          nil
+        end
+
+        def terminate_group(pid)
+          signal_group(pid, "TERM")
+          sleep(GROUP_TERM_GRACE)
+          signal_group(pid, "KILL")
+        end
+
+        def read_stream(stream)
+          output = +""
+          loop { output << stream.readpartial(16_384) }
+        rescue EOFError
+          output
+        rescue IOError
+          raise unless stream.closed?
+
+          output
+        end
+
+        def finish_readers(readers, streams)
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + READER_GRACE
+          readers.each do |reader|
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            reader.join([remaining, 0].max)
+          end
+          close_streams(streams)
+          readers.each do |reader|
+            reader.join(0.1) if reader.alive?
+            reader.kill if reader.alive?
+          end
+          readers.map { |reader| reader.value.to_s }
+        end
+
+        def close_streams(streams)
+          streams.each { |stream| stream.close unless stream.closed? }
+        end
+
+        def stop_readers(readers)
+          readers.each do |reader|
+            reader.join(0.1)
+            reader.kill if reader.alive?
+          end
+          readers.each(&:join)
+        end
+
+        def process_exit_status(status)
+          status.exitstatus || (128 + status.termsig.to_i)
+        end
+      end
+    end
+  end
+end

data/lib/samagotchi/bundle_command/try/sandbox.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "open3"
+require "rbconfig"
+require "tmpdir"
+require "yaml"
+require_relative "../../config"
+require_relative "../../cli/exit"
+require_relative "../../installed_gem"
+require_relative "../../memory_bundle"
+require_relative "../../memory_bundle/shas"
+require_relative "../../session_manager"
+
+module Samagotchi
+  class BundleCommand
+    module Try
+      class Sandbox
+        LIB_DIR = File.expand_path("../../..", __dir__)
+        CHI = File.expand_path("../../../../bin/chi", __dir__)
+        SHIPPED_DIR = MemoryBundle::SourceNormalizer::SHIPPED_DIR
+        CONFIG_DENYLIST = %w[
+          bundles hooks guardrails memories append_system_prompt recap session log web update kitty tmux broadcast
+          context_sources
+        ].freeze
+        CONFIG_DENYLIST_ENV_PREFIXES = CONFIG_DENYLIST.map do |section|
+          prefix = if section == "guardrails"
+                     SessionManager::GUARDRAILS_ENV_PREFIX.delete_suffix("_")
+                   else
+                     "SAMAGOTCHI_#{section.upcase}"
+                   end
+          prefix
+        end.freeze
+        class Error < StandardError
+          attr_reader :status
+
+          def initialize(message, status: CLI::Exit::FAILED)
+            super(message)
+            @status = status
+          end
+        end
+
+        attr_reader :root, :config_home, :state_home, :work_dir, :manifest
+
+        def initialize(path, bundle_settings: {}, cost_cap: 1, cost_cap_override: false)
+          @path = File.realpath(path)
+          @bundle_settings = bundle_settings
+          @cost_cap = cost_cap
+          @cost_cap_override = cost_cap_override
+          read_manifest
+          @root = File.realpath(Dir.mktmpdir("chi-bundle-try-"))
+          @config_home = File.join(root, "config")
+          @state_home = File.join(root, "state")
+          @work_dir = File.join(root, "work")
+          [config_home, state_home, work_dir].each { |dir| FileUtils.mkdir_p(dir) }
+          @work_dir = File.realpath(@work_dir)
+          write_config
+          @child_env = build_child_env
+        rescue StandardError
+          cleanup
+          raise
+        end
+
+        def child_env = @child_env.dup
+
+        def install
+          install_path(@path)
+          %w[guardrails cost-cap].each do |name|
+            next if @manifest.name == name
+
+            install_path(File.join(SHIPPED_DIR, name))
+          end
+          @manifest
+        end
+
+        def cleanup
+          FileUtils.rm_rf(root) if root && File.exist?(root)
+        end
+
+        private
+
+        def write_config
+          source = ConfigFile.read_yaml(env: ENV.to_h) || {}
+          data = source.to_h { |key, value| [key.to_s, value] }
+          # Drop bundles, hooks, guardrails, memories, append_system_prompt,
+          # recap, session, log, web, update, kitty, tmux, broadcast and
+          # context sources; keep model and ordinary runtime settings.
+          CONFIG_DENYLIST.each { |key| data.delete(key) }
+          data["context"] = data["context"].dup if data["context"].is_a?(Hash)
+          data["context"]&.delete("sources")
+          data["bundles"] = { "cost-cap" => { "cap" => @cost_cap } }
+          data["bundles"][@manifest.name] ||= {}
+          data["bundles"][@manifest.name].merge!(@bundle_settings)
+          data["bundles"]["cost-cap"]["cap"] = @cost_cap if @cost_cap_override
+          path = File.join(config_home, "samagotchi", "config.yml")
+          FileUtils.mkdir_p(File.dirname(path))
+          File.write(path, YAML.dump(data))
+        end
+
+        def read_manifest
+          file = File.join(@path, "manifest.yml")
+          raise Error.new("chi bundle try: not a bundle: #{@path} (chi bundle new NAME)", status: CLI::Exit::USAGE) unless File.file?(file)
+
+          text = File.read(file)
+          stale = MemoryBundle::Shas.stale(@path, text)
+          unless stale.empty?
+            raise Error, "chi bundle try: stale or placeholder sha256 in manifest.yml; run chi bundle check --fix"
+          end
+
+          @manifest = MemoryBundle::Manifest.read(dir: @path)
+          if @manifest.meta?
+            raise Error.new("chi bundle try: profile bundles cannot be tried directly", status: CLI::Exit::USAGE)
+          end
+
+          @manifest
+        rescue MemoryBundle::Manifest::ValidationError => e
+          raise Error, "chi bundle try: #{e.message}"
+        rescue MemoryBundle::Shas::Error => e
+          raise Error, "chi bundle try: #{e.message}"
+        rescue Psych::Exception => e
+          raise Error, "chi bundle try: manifest.yml is not valid YAML (#{e.message})"
+        end
+
+        def install_path(path)
+          out, err, status = Open3.capture3(child_env, RbConfig.ruby, "-I", LIB_DIR, CHI,
+                                            "bundle", "install", path, "--force", chdir: work_dir)
+          return if status.success?
+
+          message = [out, err].reject(&:empty?).join("\n").strip
+          raise Error, "chi bundle try: #{message.empty? ? "bundle install failed" : message}"
+        end
+
+        def build_child_env
+          env = ENV.to_h
+          SessionManager::SESSION_MARKER_ENV.each { |key| env.delete(key) }
+          env.delete("SAMAGOTCHI_LOG_FILE")
+          env.delete("SAMAGOTCHI_LOG_DISABLE")
+          env.delete("SAMAGOTCHI_SKIP_SYSTEM_BUNDLE")
+          env.delete("SAMAGOTCHI_ENV") if env["SAMAGOTCHI_ENV"] == "test"
+          env.delete("SAMAGOTCHI_INSTALLED_VERSION")
+          env.delete_if do |key, _|
+            key.start_with?(SessionManager::WORKER_ENV_PREFIX) || key == SessionManager::BOOT_FALLBACK_ENV ||
+              CONFIG_DENYLIST_ENV_PREFIXES.any? { |prefix| key == prefix || key.start_with?("#{prefix}_") }
+          end
+          env.merge!(
+            "HOME" => Dir.home,
+            "SAMAGOTCHI_KEYCHAIN" => "on",
+            "XDG_CONFIG_HOME" => config_home,
+            "XDG_STATE_HOME" => state_home,
+            "SAMAGOTCHI_RECAP_ENABLED" => "false",
+            "SAMAGOTCHI_CACHE_WARMUP" => "off"
+          )
+          env.merge!(InstalledGem.unbundled_env_changes(env)) if InstalledGem.spec
+          env
+        end
+      end
+    end
+  end
+end