samagotchi 0.12.0 → 0.13.0

data/docs/hooks.md

@@ -9,7 +9,8 @@ hooks. See [Plugins](plugins.md).
 
 ## Configuration
 
-Add a `hooks:` section to your global config file (`~/.config/samagotchi/config.yml`):
+Add a `hooks:` section to your global config file (`$XDG_CONFIG_HOME/samagotchi/config.yml`, `$XDG_CONFIG_HOME`
+defaulting to `~/.config`):
 
 ```yaml
 hooks:
@@ -48,15 +49,15 @@ The plugin class must respond to `#call(event)` — duck-typed, no base class re
 
 | Event | When it fires | Event payload |
 |-------|--------------|---------------|
-| `:session_start` | First turn of the session | `{ type: :session_start, session_id: "..." }` |
+| `:session_start` | The first turn this chi process runs for the session (so again after `--resume`, a worker that idle-exited and woke, or a restart) | `{ type: :session_start, session_id: "..." }` |
 | `:before_turn` | Before each turn starts | `{ type: :before_turn, session_id: "...", prompt: "..." (nil on a continue), messages: [...] (the history before this turn) }` |
-| `:after_turn` | After a turn completed or was cancelled (not after one that failed) | `{ type: :after_turn, status: "completed" \| "canceled", present: (see [Presenting the answer](#presenting-the-answer-display-only)), messages: [...] (the conversation the turn stored; a cancelled or empty turn ends it with a `kind: turn_note` system message, and a context line is `kind: context`, see [sessions.md](sessions.md#notes-a-turn-leaves-for-the-model)) }` |
+| `:after_turn` | After a turn completed or was stopped once the model was asked (not after one that failed, was cut short by an interrupt signal (SIGINT), or was stopped before its `:before_turn` hooks) | `{ type: :after_turn, status: "completed" \| "canceled", present: (see [Presenting the answer](#presenting-the-answer-display-only)), messages: [...] (the conversation the turn stored; a cancelled or empty turn ends it with a `kind: turn_note` system message, and a context line is `kind: context`, see [sessions.md](sessions.md#notes-a-turn-leaves-for-the-model)) }` |
 | `:before_generation` | Before each LLM API call (both loops) | `{ type: :before_generation, iteration: N }` |
 | `:after_generation` | After LLM returns (both loops); not after a generation a hook cut (`stop_generation`) | `{ type: :after_generation, iteration: N, response: "...", messages: [...] (the conversation as sent) }` |
 | `:generation_progress` | While the response streams, in batches (see [Watching the stream](#watching-the-stream)) | `{ type: :generation_progress, iteration: N, thinking: "..." (new since the last fire), text: "..." (new visible text), thinking_chars: N, text_chars: N (this generation so far), elapsed_ms: N }` |
 | `:before_tool_call` | Before tool dispatch (and before `tool_call_started`) | `{ type: :before_tool_call, iteration: N, call: {...}, params: "...", guardrail: Verdict, context: {...}, targets: {...}, blocked: false, block_reason: nil }` |
 | `:after_tool_call` | After tool execution | `{ type: :after_tool_call, iteration: N, tool: "read", output: "..." (capped at max_tool_output_chars), status: "ok" \| "error" \| "blocked" \| "stopped" }` |
-| `:session_end` | After every turn (turn-level lifecycle) | `{ type: :session_end, session_id: "..." }` |
+| `:session_end` | After each turn `:after_turn` fires for, after it (turn-level lifecycle) | `{ type: :session_end, session_id: "..." }` |
 
 Every event also carries the hook runtime (next section): `hook:` (the label
 of the hook about to run) and the callables `notify:`, `ask_user:`,
@@ -268,7 +269,7 @@ You can also register hooks programmatically during a turn (they are cleared
 automatically after each `run_turn`):
 
 ```ruby
-engine = Samagotchi::Engine.new(mode: :assist)
+engine = Samagotchi::Engine.new
 engine.register_hook(:before_turn) do |event|
   puts "Turn starting..."
 end
@@ -404,7 +405,8 @@ stripped of surrounding whitespace, except file text, an edit's
 
 A `write`'s `content:` is the file text; an `edit` carries `old_text:` and
 `new_text:` (its `content:` is `""`). A plugin or MCP tool's call has its
-arguments whole on `args:` (string keys) instead.
+arguments whole on `args:` (string keys) instead, and its `content:` is those
+arguments as JSON.
 
 ## Bundle Hooks (unified workflow bundle)
 
@@ -439,6 +441,7 @@ hooks:
     on_error: log
     priority: 100
 trust_level: reviewed        # reviewed | experimental (default)
+requires_chi: ">= 0.12.0"    # optional: a gem-style requirement, as for plugins
 needs: [gh]                  # optional: outside commands the memories use (docs/memory.md#bundles-that-need-outside-commands)
 ```
 
@@ -449,7 +452,8 @@ Notes:
 - `sha256` is integrity (not authenticity). No signing in v1. Install records the sha256 of the copied file; at `Engine.new` a hook whose file differs is not loaded (reinstall the bundle after editing one by hand).
 - Hook code is the bundle author's source of truth: on upgrade, hooks are overwritten; if the installed file was locally modified, a warning is emitted (`was locally modified; overwriting`).
 - `on_error` defaults to `skip` for every event, `:before_tool_call` included: a raising hook is silent and the call goes ahead. `log` warns. `fail_closed` (only on `:before_tool_call`; on any other event it acts as `skip`) denies the call the hook raised on. Choose `fail_closed` for a hook that is a guardrail, whose failure should stop tool calls rather than let them through.
-- A `fail_closed` `:before_tool_call` hook is required: if it is missing, fails to load or its sha256 differs, chi denies every tool call until it is fixed.
+- `requires_chi`: when this chi doesn't meet it, none of the bundle's hooks load (each is reported, `not loaded: it requires chi …`), as for a [plugin](plugins.md#loading-and-when-it-fails).
+- A `fail_closed` `:before_tool_call` hook is required: if it is missing, fails to load, its sha256 differs or chi doesn't meet the bundle's `requires_chi`, chi denies every tool call until it is fixed.
 - A bundle can also ship YAML rules in `guardrails/*.yml`; see [Guardrails](guardrails.md#the-guardrails-bundle).
 - 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)).
@@ -459,8 +463,8 @@ Notes:
 
 Lifecycle:
 
-- `chi bundle install <source>` copies `hooks/*.rb` to `~/.config/samagotchi/memories/.bundles/<name>/hooks/` and persists metadata + `trust_level` + `source_commit` (git HEAD) to provenance.
-- `Engine.new` loads `config.yml` hooks first, then bundle hooks via `Provenance.each_installed_holding_hooks` → `Hooks::BundleLoader.load`. Bundle hooks are process-scoped (they survive the per-turn `clear_hooks`; only plain hooks are cleared). Experimental bundles emit a one-line startup warning.
+- `chi bundle install <source>` copies the hook files its manifest's `hooks:` map lists (only those; with no `hooks:` map, every `hooks/*.rb`) to `$XDG_CONFIG_HOME/samagotchi/memories/.bundles/<name>/hooks/` (`$XDG_CONFIG_HOME` defaults to `~/.config`) and persists metadata + `trust_level` + `source_commit` (git HEAD) to provenance.
+- `Engine.new` loads `config.yml` hooks first, then bundle hooks via `MemoryBundle::Provenance.each_installed(holding: :hooks)` → `Hooks::BundleLoader.load`. Bundle hooks are process-scoped (they survive the per-turn `clear_hooks`; only plain hooks are cleared). Experimental bundles emit a one-line startup warning.
 - `chi bundle status`, `diff`, `uninstall`, `build` are hook-aware (counts, metadata, removal).
 
 ## The source-links bundle

data/docs/memory.md

@@ -2,10 +2,12 @@
 
 Samagotchi stores memories in two scopes:
 
-- Project scope: `~/.config/samagotchi/memories/projects/<name>_<hash>/`, one folder per
+- Project scope: `$XDG_CONFIG_HOME/samagotchi/memories/projects/<name>_<hash>/`, one folder per
   git repository (named and hashed by its root), shared by all its worktrees and
   subdirectories; outside a repository, one per working directory
-- System scope: `~/.config/samagotchi/memories`
+- System scope: `$XDG_CONFIG_HOME/samagotchi/memories`
+
+`$XDG_CONFIG_HOME` falls back to `~/.config` when unset.
 
 Tool behavior:
 
@@ -19,7 +21,7 @@ Tool behavior:
 
 Each memory entry may have a companion file named `<name>.<model-key>.md` in the same scope directory. When the entry is read under a matching model, the overlay body is appended automatically, separated by the standard `---` separator with a `Model-specific guidance (<key>):` header.
 
-- **Key derivation**: The harness normalizes the full model name (lowercase, replace non-alphanumeric with `-`, squeeze dashes) to derive the file key. For example, `qwen3.6-35b-a3b` → `qwen3-6-35b-a3b`.
+- **Key derivation**: The harness normalizes the model name sent to the server, without its host prefix (`box:qwen3.6-35b-a3b` keys as `qwen3.6-35b-a3b`; an alias keys as its target, and the alias's own key is read when the target has no overlay) (lowercase, replace non-alphanumeric with `-`, squeeze dashes) to derive the file key. For example, `qwen3.6-35b-a3b` → `qwen3-6-35b-a3b`.
 - **Saving overlays**: Pass `current_model_only: true` to `memory_write` (the harness resolves the model key automatically). This writes the content as `<name>.<model-key>.md` and skips index maintenance.
 - **Dormancy**: Overlays are only active under the matching model key; other models see the base entry only.
 - **Invariant**: The base entry is the contract. Overlays only add model-specific guidance and never contradict the base protocol.

data/docs/plugins.md

@@ -24,7 +24,7 @@ version: 1.0.0
 plugin:
   file: plugin.rb
   sha256: sha256:6a1a7022…   # shasum -a 256 plugin.rb
-requires_chi: ">= 0.1.28"    # optional: a gem-style requirement (">= 0.1.28, < 0.2")
+requires_chi: ">= 0.1.28"    # optional: a gem-style requirement (">= 0.1.28, < 0.2"); the bundle's hooks/ check it too
 needs: [gh]                  # optional: outside commands it relies on (see memory.md#bundles-that-need-outside-commands)
 ```
 
@@ -73,7 +73,7 @@ Settings work as they do for hooks ([hooks.md](hooks.md#settings)). An
 
 ### `chi.command(name, description, anytime: false) { |args, ctx| … }`
 
-This adds a slash command. `name` is `/name` (a–z, 0–9, `_` and `-`).
+This adds a slash command. `name` is `/name`: a lowercase letter first, then a–z, 0–9, `_` and `-`, at most 32 characters after the `/`.
 `args` is the text after the name, stripped, or `""` when there is none. The
 block returns the text to show (a String), or nil to show nothing. If the
 block raises, the user sees `/name: <error>`.
@@ -638,8 +638,8 @@ only against this API (`lib/samagotchi/bundles/btw/plugin.rb`).
   0.1.0 shipped `btw.md` as one, and `chi bundle upgrade btw` leaves that file
   (and its index line) behind. Drop it with `chi bundle uninstall btw`, then
   `chi bundle install btw`. After an upgrade already ran, delete
-  `~/.config/samagotchi/memories/btw.md` and its `**btw**` line in `index.md`
-  there by hand.
+  `$XDG_CONFIG_HOME/samagotchi/memories/btw.md` (`$XDG_CONFIG_HOME` defaults to
+  `~/.config`) and its `**btw**` line in `index.md` there by hand.
 
 ## The mcp bundle
 

data/docs/sessions.md

@@ -25,7 +25,7 @@ A session is deleted if **expired by age OR overflow by count** (unless `keep_st
 
 <a id="archiving-a-session"></a>**Archiving a session:** `chi sessions archive ID...`, `/archive` in a terminal and the Web UI's `archive` go through `SessionManager.archive_session`: it writes `<id>/archived` (`{"archived_at": …}`; not a session.json field, which every save rewrites) for the session and its delegated children. `Session.list` leaves archived sessions out unless `include_archived:`, and everything built on it follows: `chi sessions list` (`--archived` shows them, `[archived]`), the summaries (`--live`, json/tsv, the desktop panel, the agent's `list_sessions`) and the retention prune, which neither deletes nor counts them against `max_count`. `children_of` (max_children, `delegate_result`) still sees them, and `--resume`/`--attach ID`, `chi send`/`chi note ID` reach them as before. Refused: a turn running in the session or in one of its children (naming the child; 409 `busy` on the web), a plain REPL owning it (`owned_by_tui`), a `chi scratch` session (`scratch`). A live idle worker is stopped first, and the marker is written even if it is still shutting down. Input a human typed brings a session back (`{"unarchived_at": …}`): a prompt from the web, an attached or plain terminal or `chi send` (origin `web:*`, `tui:*`, `cli:send`, none), steering merged into a running turn, a `/continue` answer or a question answered; a delegate's follow-up, a plugin's turn, a reminder, the idle recap, a note and just opening it don't. A child's input brings only the child back. The retention sweep ages an unarchived session from when it was unarchived, so unarchiving an old session doesn't let the next sweep take it. `/archive` leaves the session first, as `/exit` does, then archives it: in an attached terminal the worker is asked to exit (one that stays up for another UI is stopped by the archive; a running turn refuses it), and an empty session is discarded instead; `chi scratch` refuses it. `chi sessions unarchive ID...` and the web's `unarchive` bring back the whole family. Web routes: `POST /api/sessions/:id/archive` (200 `{status, session_id, archived, stopped, discarded}`, ids) and `POST /api/sessions/:id/unarchive` (200 `{status, session_id, unarchived}`). The session hub and `GET /api/sessions` keep archived sessions, `archived: true` in their summaries: the page leaves them out of the strip, its count and the list at render, and "include archived" by the all-sessions search shows them, dimmed with an `archived` badge. The info bar reads `archive · stop · delete` (`unarchive` on an archived one); archiving the open session stays on it, with an Undo toast.
 
-**Lazy sweep:** automatic prune runs at most once per 24h on `GET /api/sessions` (Web). No background thread or cron. Manual prune is always available.
+**Lazy sweep:** automatic prune runs only while `chi web` runs, at most once per `session.sweep_interval_hours` (default 24): the web's session hub gives it a chance on its periodic full scan, and `GET /api/sessions` does too. No cron, and a terminal-only chi never sweeps. Manual prune is always available.
 
 **CLI:**
 
@@ -40,6 +40,8 @@ chi sessions prune [--dry-run] [--days N] [--keep N] [--keep-status running,...]
 chi sessions clean [--dry-run] [--days N]             # test sessions: all, or older than N days
 ```
 
+A session whose worker waits for an answer (a question, a hook's question or a guardrail approval) reads `waiting` in the status column, and json has `waiting: "question"|"approval"|"hook"` and `waiting_id`, the question's id for `chi answer --question` (both null otherwise). Only while a worker runs it: a question a dead worker left in the file shows the saved status. Answer it with `chi answer`, the web or `chi --attach ID`; `chi sessions stop ID` frees the worker instead.
+
 Examples:
 
 ```sh
@@ -146,7 +148,7 @@ pbpaste | chi send 3fa2                             # the clipboard is the messa
 - It goes through the same path as the web composer (`SessionManager.deliver_turn`): the worker's Bridge when it is up, so every attached UI shows it as your message (client id `cli:send`, shown like any user message); the input file when the worker is on its way out. During a running turn it is merged into that turn at the next step, like a message typed then.
 - A session with no worker gets one started (like `--attach` or the web composer). A session open in a plain REPL (`--no-shared`) refuses it. Only sessions on this machine: Bridges listen on 127.0.0.1.
 - Fire and forget: it returns once the message is queued and never prints the answer; that shows in whatever is attached. A guardrail "ask" waits for a UI to answer it, so with nothing attached the turn stalls there until one attaches (`chi --attach ID`).
-- `--image PATH` (repeatable, up to 20) sends images with the message, as the web composer's chips do. Each file is read once before anything is sent (bmp, tiff and heic converted to png, large ones downscaled, as for `@path`); a missing file or one that isn't an image is a usage error (exit 2) and nothing is sent. Each session gets its own copy in `<session>/images/`. Text is still required (`-m` or stdin; context alone counts), also with `--wait`. The session's model must see images: one known not to (the host's model list says text-only, `vision: false` in `models:` or `hosts:`, a native llama.cpp without a vision model) is refused before anything is sent, with the reason (`<id>  refused: gemma can't take images (…); send text only or switch the model (/model)`); the other sessions of the same send still get it, and the exit is 1. With `--new` nothing is started. When chi can't tell (a native host whose `/props` doesn't answer, a list that doesn't say), the message is sent as before and a text-only model fails the turn in the session. A running turn doesn't take images mid-turn: the message runs as the next turn, and the line says `(runs after the current turn)`. With `--new` the session starts idle with the message as its preview, then the message goes in as its first turn once its worker is up (`<id>  started with 1 image`); if the worker doesn't come up in 5 s the session is kept, with its id on the `failed:` line.
+- `--image PATH` (repeatable, up to 20) sends images with the message, as the web composer's chips do. Each file is read once before anything is sent (bmp, tiff and heic converted to png, large ones downscaled, as for `@path`); a missing file or one that isn't an image stops the send (exit 1; with `--wait --format json`, an `error` line) and nothing is sent; more than 20 is a usage error (exit 2). Each session gets its own copy in `<session>/images/`. Text is still required (`-m` or stdin; context alone counts), also with `--wait`. The session's model must see images: one known not to (the host's model list says text-only, `vision: false` in `models:` or `hosts:`, a native llama.cpp without a vision model) is refused before anything is sent, with the reason (`<id>  refused: gemma can't take images (…); send text only or switch the model (/model)`); the other sessions of the same send still get it, and the exit is 1. With `--new` nothing is started. When chi can't tell (a native host whose `/props` doesn't answer, a list that doesn't say), the message is sent as before and a text-only model fails the turn in the session. A running turn doesn't take images mid-turn: the message runs as the next turn, and the line says `(runs after the current turn)`. With `--new` the session starts idle with the message as its preview, then the message goes in as its first turn once its worker is up (`<id>  started with 1 image`); if the worker doesn't come up in 5 s the session is kept, with its id on the `failed:` line.
 - One line per session: `sent`, `sent with 2 images`, `sent (the running turn picks it up)`, `sent (started its worker)`, `refused: …` or `failed: …`. Exit 0 when all were sent, 1 when any was refused, failed or not found, 2 for a usage error. There is no `--all`.
 
 The Automator action above works for messages too: swap its last line for `pbpaste | "$chi" send -m "what do you make of this?" $(print -r -- "$picked" | cut -f1)`.
@@ -166,10 +168,11 @@ chi send --wait 3fa2                                   # sends nothing: waits fo
 - `--new` takes no ids (one new session per call). `--dir DIR` is its folder, and so its project (default the current one); `--model M` its model (default the configured one; the name isn't checked up front, a wrong one fails the worker's first turn).
 - `--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 run after it, and its reply would come back as the answer.
-- Exit codes with `--wait`: 0 answered; 3 the turn waits for an answer from you (a question or a guardrail approval), with the line `waiting for an answer: …; open it: chi --attach ID or the web`, and the session keeps waiting; 1 the turn ended without a reply (canceled, failed or empty), the worker failed or vanished, the session was stopped, or `--timeout S` passed; 130 on Ctrl-C, which leaves the turn running (`still running: chi --attach ID`). There is no default timeout.
-- `--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. A running session is fine (that is the point), so after exit 3 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).
+- Exit codes with `--wait`: 0 answered; 3 the turn waits for an answer from you (a question, a hook's question or a guardrail approval), 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`, `no_answer`, `error`, `worker_gone` or `stopped` with a `detail` line (exit 1). 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. 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).
 - 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 guardrail ask until someone opens it; left alone it idle-exits after `session.idle_exit_minutes` like any worker. These are ordinary sessions: delete them like any other.
+- 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.
 
 ## Delegating
 
@@ -177,7 +180,7 @@ The `delegate` tool hands a task to a **child session**: an ordinary chi session
 
 - `delegate(task, model:, session:, wait:, timeout:)`: starts a child and, by default, waits for its reply (`wait: false` returns at once, so several children can run side by side; `timeout`, default 600 s, leaves a slow child running; 0 checks once without waiting). With `session:` (a child's id or prefix) the task goes to that child as a follow-up instead, delivered like `chi send` (client id `delegate:<parent short id>`, shown as `delegate>` in the child's UIs); only this session's children take one.
 - `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.
-- What a wait returns, `session: <id>` then `status:` and the text: `done` with the reply after a `---` line; `waiting_for_answer` as soon as the child opens a question or a guardrail approval (nothing is answered for it: attach or use the web, then wait again); `canceled` when the parent's own turn is canceled (the child keeps running; the next turn can wait again); `no_reply` when the child's turn ended with nothing to say (canceled, failed or empty: its session shows what happened); `error` (its worker crashed) or `stopped` (`chi sessions stop`) at once; `running` on timeout. A reply saved before the child's worker idle-exited is returned at once.
+- What a wait returns, `session: <id>` then `status:` and the text: `done` with the reply after a `---` line; `waiting_for_answer` as soon as the child opens a question or a guardrail approval, 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); `canceled` when the parent's own turn is canceled (the child keeps running; the next turn can wait again); `no_reply` when the child's turn ended with nothing to say (canceled, failed or empty: 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. A reply saved before the child's worker idle-exited is returned at once.
 - Every child starts with the shipped `delegated` system memory preloaded (`preloaded_memory_names: ["system/delegated"]`; `--mute delegated` would hide it): put everything in the final reply, don't delegate further, don't write memories or change config, stay in the folder. Its system prompt also says `Delegated by session <parent id>`. The parent's own `--mute` list does not carry over.
 - Limits: a child cannot `delegate` (depth 1; the tool refuses), and one session may have at most `session.max_children` (default `4`, env `SAMAGOTCHI_SESSION_MAX_CHILDREN`) children running at a time, counted from the session files (a finished or idle-exited child does not count; one whose worker is still starting does, for 15 s). A refused call creates no session. Nothing stops children with the parent: `chi sessions stop ID` does.
 - The link is the session's `parent_id`, written before the worker starts, so a respawn keeps it; `GET /api/sessions` and `/api/sessions/:id` carry it, and `SessionManager.children_of` lists a parent's children.

data/docs/sub-agent.md

@@ -0,0 +1,128 @@
+# chi as a sub-agent
+
+Another agent (Claude Code, Codex, a script) can hand a task to chi and get the
+answer back, the way you would from a terminal: `chi send --new --wait` starts a
+session in a background worker and prints its reply. The session is an
+ordinary one, so you (the human) can watch it live in `chi web` or join it with
+`chi --attach ID`.
+
+When chi's model asks a question (`ask_user_question`), a hook asks one, or a
+guardrail wants an approval, chi stops and hands the question up: the wait ends
+with exit 3 and the question, its options and the command that answers it. The
+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.
+
+## The commands
+
+```sh
+chi send --new --wait --format json [--dir D] [--model M] [--timeout S] -m "task"
+chi send --wait --format json [--timeout S] [-m "follow-up"] ID
+chi answer ID --question QID (--option N|LABEL)... [--text T] [--timeout S] [--format json]
+chi answer ID --question QID --dismiss [--timeout S] [--format json]
+```
+
+`chi answer` waits after answering, the same way `chi send --wait` does, so the
+next question comes back as exit 3 again. `--option` is 1-based or the label,
+repeated on a multi-select question. `--text` is free text (where the question
+allows it) or the reason for a Deny. `--dismiss` leaves the question
+unanswered: the model doesn't do what it asked about and finishes its reply.
+
+Exit codes, both commands:
+
+| Exit | `status` | Meaning |
+|---|---|---|
+| 0 | `answered` | `text` is chi's reply |
+| 3 | `question` | chi waits for an answer: `question`, `answer_with` |
+| 4 | `running` | `--timeout` passed; the turn goes on, wait again |
+| 1 | `failed`, `canceled`, `no_answer`, `error`, `worker_gone`, `stopped` | `detail` says what happened |
+| 2 | (no JSON) | usage error, or an option the question doesn't offer |
+| 130 | `running` | Ctrl-C; the turn goes on |
+
+With `--format json` stdout is one JSON object (see
+[Starting a session](sessions.md#starting-a-session) for every field):
+
+```json
+{"status":"question","session_id":"297da360-…","question":{"id":"3f1c…","kind":"question",
+  "text":"Which file should I read?","options":["README.md","NOTES.md"],"multi_select":false,
+  "allow_freeform":false},"answer_with":"chi answer 297da360-… --question 3f1c… --option N"}
+```
+
+`kind` is `question` (the model's), `hook`, or `approval`, which adds the tool,
+command, folder, rule and reason.
+
+## Approvals
+
+An approval is a guardrail rule with `verdict: ask`: its user said "ask me". So
+a parent may deny it (`--option Deny --text "why"`, `--text` alone, or
+`--dismiss`) but not allow it: `chi answer` refuses an Allow with exit 1 and
+`allowing a tool call is up to the user: deny it (--option Deny --text WHY),
+and tell your user`. For an approval, the question block and `answer_with` give
+the deny command, not `--option N` or `chi --attach`. With
+`guardrails.parent_approvals: once` in chi's config.yml (it has no environment
+variable), "Allow once" goes through; the wider scopes never do,
+and neither does any allow on chi's own config, hooks or guardrail rules. See
+[Guardrails](guardrails.md#approvals-from-a-parent-agent).
+
+An answer typed into `chi --attach` or the REPL counts as a parent's too when
+stdin isn't a terminal or an agent marker (`CLAUDECODE`, `AI_AGENT`,
+`SAMAGOTCHI_PARENT_SESSION`) is set.
+
+The worker checks it again with its own config.yml. The guardrails settings
+have no environment variables, and a worker drops any `SAMAGOTCHI_GUARDRAILS_*`
+it inherits; but a parent that sets `XDG_CONFIG_HOME` picks which config.yml a
+worker it starts or wakes reads. Still, this guards a parent that follows its instructions,
+not a security boundary: the worker's Bridge and `chi web` on localhost take
+answers from any local process.
+
+## Things to know
+
+- A question waits for as long as it takes: the worker doesn't idle-exit while
+  one is open. `chi sessions list` shows such sessions as `waiting`
+  (`--format json`: `waiting_id` is the question's id);
+  `chi sessions stop ID` ends one.
+- If the worker dies while a question waits, the question goes with it.
+  `chi answer` then exits 1 and says to send the task again
+  (`chi send --wait -m "…" ID`); a wait ends with `worker_gone` (exit 1).
+- A follow-up (`chi send --wait -m "…" ID`) to a session waiting for an answer
+  isn't sent: it exits 1 with the `chi answer` command for the question.
+- An answer to a question that is no longer open (you answered it in the web
+  first) isn't sent; `chi answer` says so and waits for what comes next.
+- `chi send --wait` and `chi answer` don't read stdin unless it's a pipe or a
+  file. Agent shells usually pass `/dev/null`, which is fine.
+
+## Instructions for the parent agent
+
+Paste this into the parent's `CLAUDE.md` or `AGENTS.md`:
+
+```markdown
+## Using chi as a sub-agent
+
+Start a task: `chi send --new --wait --format json --timeout 500 -m "<task>"`
+(add `--dir <project>`). Read the JSON on stdout:
+
+- `status: answered` (exit 0): `text` is chi's reply.
+- `status: question` (exit 3): chi is paused, waiting for an answer. If the answer
+  is clear from your task and context, answer it yourself. Otherwise ask your
+  user, showing them the question and its options; if you can't ask (no user in
+  this run), stop and report the question and options instead of guessing. To
+  answer, run the `answer_with` command with `--option N` (1-based, repeat for
+  multi-select) and/or `--text "…"`. It returns the same JSON. If you won't
+  answer, add `--dismiss` instead: chi does nothing it asked about, finishes
+  with what it found, and the reply comes back (exit 0).
+- `question.kind: approval`: chi wants to run something its user's guardrails
+  flagged, and allowing it is up to your user. Deny it (the `answer_with`
+  command: `--option Deny --text "why"`), and tell your user what it wanted to
+  run and why. Never allow it yourself, through `chi answer`, a piped
+  `chi --attach` or chi's web API.
+- `status: running` (exit 4): still working. Wait again:
+  `chi send --wait --format json --timeout 500 <session_id>`.
+- Anything else (exit 1): report `detail` to your user. `chi --attach <session_id>`
+  shows the session.
+
+Run each chi command on its own, nothing chained after it: the exit code comes
+back with the output. Talk to chi only through these commands; never call its
+Bridge or web API directly. Follow-ups in the same session:
+`chi send --wait --format json --timeout 500 -m "…" <session_id>`.
+Keep `--timeout` under your shell tool's limit (Claude Code: 600 s per call).
+```

data/lib/samagotchi/answer_command.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require_relative "session"
+require_relative "session_manager"
+require_relative "bridge_client"
+require_relative "reply_wait"
+require_relative "parent_report"
+require_relative "guardrails/parent_approvals"
+require_relative "cli/command"
+require_relative "cli/flags"
+require_relative "cli/parent_wait"
+
+module Samagotchi
+  # `chi answer`: answer the question a session's worker waits on (exit 3
+  # from chi send --wait), then wait for what comes next and print it the
+  # same way: the reply (0), the next question (3), still running (4). It is
+  # how a parent agent running chi as a sub-agent answers; the web and
+  # chi --attach answer the same question. See docs/sub-agent.md.
+  #
+  # An approval is the user's to allow: a parent may deny it, and allow it
+  # only "once" when guardrails.parent_approvals (config.yml) says so. It is
+  # checked here and again by the worker, which sees the answer marked as
+  # chi answer's. That guards an honest but eager parent, not a boundary:
+  # the Bridge and the localhost web take answers from any local process.
+  class AnswerCommand
+    include CLI::Command
+    include CLI::ParentWait
+
+    USAGE = <<~TEXT
+      Usage: chi answer ID --question QID (--option N|LABEL)... [--text T] [--timeout S] [--format json]
+             chi answer ID --question QID --dismiss [--timeout S] [--format json]
+        Answers the question session ID waits on (chi send --wait exits 3
+        with it), then waits for what comes next and prints it as chi send
+        --wait does.
+        --question QID  the question's id (chi send --wait prints it); a
+                        question no longer open is not answered
+        --option N|LABEL
+                        an option, by number (1-based) or label; repeat
+                        on a multi-select question
+        --text T        free text, where the question allows it; with an
+                        approval, the reason for a Deny (text alone denies)
+        --dismiss       leave it unanswered: chi does nothing it asked
+                        about and finishes its reply
+        --timeout S     give up waiting after S seconds (exit 4)
+        --format json   one JSON object on stdout (see chi send --help)
+        An approval (a guardrail's ask) can be denied here: deny it, and
+        tell your user; allowing it is the user's. With
+        guardrails.parent_approvals: once, "Allow once" is let through.
+        Exit: 0 answered, 1 failed, refused or the worker is gone, 2
+        usage or an option the question doesn't offer, 3 a question waits,
+        4 still running (--timeout), 130 Ctrl-C.
+    TEXT
+
+    FLAGS = CLI::Flags.new(help: CLI::Command::HELP_WORDS) do |f|
+      f.value "--question"
+      f.value "--option", key: :options, repeat: true
+      f.value "--text"
+      f.switch "--dismiss"
+      f.value "--timeout"
+      f.value "--format"
+    end
+
+    def initialize(argv, stdout: $stdout, stderr: $stderr, state_dir: nil)
+      @argv = argv.dup
+      @stdout = stdout
+      @stderr = stderr
+      @state_dir = state_dir || Session.default_state_dir
+    end
+
+    private
+
+    def command_name = "chi answer"
+
+    def parse
+      parsed = parse_flags(FLAGS, @argv, options: [])
+      return parsed if parsed.is_a?(Integer)
+
+      options = parsed.options
+      return usage_error("give one session id") unless parsed.args.size == 1
+      return usage_error("--question QID is required (chi send --wait prints it)") if options[:question].to_s.strip.empty?
+      if options[:dismiss]
+        return usage_error("--dismiss takes no --option or --text") if !options[:options].empty? || options[:text]
+      elsif options[:options].empty? && options[:text].nil?
+        return usage_error("nothing to answer with: --option, --text or --dismiss")
+      end
+      return usage_error("--format takes text or json") if options[:format] && !FORMATS.include?(options[:format])
+      if options[:timeout]
+        options[:timeout] = Float(options[:timeout], exception: false)
+        return usage_error("--timeout takes seconds") unless options[:timeout]&.positive?
+      end
+      options.merge(id: parsed.args.first)
+    end
+
+    # Answer, then wait for what comes next.
+    # @return [Integer] the exit status
+    def run_parsed(options)
+      id = resolve(options[:id]) or return 1
+      qid = options[:question].strip
+      session = Session.load(id, state_dir: @state_dir)
+      pending = session.pending_question
+      # Taken before the answer goes in, with the question answered as the
+      # one already reported: the file keeps it until the turn thread
+      # wakes, and it must not come back as exit 3.
+      cursor = ReplyWait.newest_reply(id, state_dir: @state_dir)
+      baseline = ReplyWait.baseline_of(session, question_id: qid)
+
+      if pending && pending[:id].to_s == qid
+        selected = selection(pending, options) or return @selection_status
+        refusal = approval_refusal(pending, selected, id)
+        return failure(refusal) if refusal
+
+        posted = post(id, qid, selected, options)
+        return posted if posted.is_a?(Integer)
+      elsif session.status != Session::STATUS_RUNNING
+        return failure("no question #{qid} waits in #{id[0, 8]}; nothing to answer")
+      else
+        not_open(qid)
+      end
+      # Answered here, or no longer open (answered elsewhere, or a newer
+      # question): what comes next either way.
+      wait_for_reply(id, cursor: cursor, baseline: baseline, timeout: options[:timeout])
+    end
+
+    # The labels to send. A number is an option's place (1-based); an
+    # exact label wins over a number.
+    # @return [Array<String>, nil] nil after a usage error
+    def selection(pending, options)
+      offered = Array(pending[:options]).map(&:to_s)
+      labels = options[:options].map do |given|
+        next given if offered.include?(given)
+
+        index = Integer(given, exception: false)
+        next offered[index - 1] if index&.between?(1, offered.size)
+
+        listed = offered.each_with_index.map { |label, i| "#{i + 1}. #{label}" }.join(", ")
+        @selection_status = usage_failure("no option #{given}; the options: #{listed}")
+        return nil
+      end
+      if labels.uniq.size > 1 && !pending[:multi_select]
+        @selection_status = usage_failure("one option only: the question is single-select")
+        return nil
+      end
+      labels.uniq
+    end
+
+    # Why a parent may not give this answer to an approval, or nil
+    # (Guardrails::ParentApprovals, with this process's config.yml). A
+    # Deny, text alone or a dismissal always passes: each one denies. The
+    # worker checks it again with its own config.
+    def approval_refusal(pending, selected, id)
+      offered = Array(pending[:options]).map(&:to_s)
+      indices = selected.map { |label| offered.index(label) }
+      reason = Guardrails::ParentApprovals.refusal(pending, indices, setting: Guardrails::ParentApprovals.setting)
+      reason && Guardrails::ParentApprovals.message(reason)
+    end
+
+    # Post the answer (or the dismissal) to the live worker's Bridge.
+    # @return [Integer, nil] an exit status when it didn't go in; nil to
+    #   wait (it went in, or the question was no longer open: 409)
+    def post(id, qid, selected, options)
+      client = BridgeClient.discover(id, session_dir: Session.session_dir(id, state_dir: @state_dir))
+      return failure(worker_gone(id)) unless client
+
+      reply = nil
+      2.times do
+        reply = if options[:dismiss]
+                  client.dismiss_question(id: qid)
+                else
+                  client.answer(id: qid, selected: selected, freeform: options[:text],
+                                client_id: Guardrails::ParentApprovals::CLIENT_ID)
+                end
+        break unless reply.status == 408
+      end
+
+      case reply.status
+      when 200 then nil
+      when 409 then not_open(qid)
+      when 400 then usage_failure(reply.json&.dig("detail") || "the worker refused the answer")
+      # The worker's own guardrails.parent_approvals refused the allow.
+      when 403 then failure(reply.json&.dig("detail") || "the worker refused the allow: deny it, and tell your user")
+      when 408 then failure("the worker did not take the answer in time; the question is still open: try again")
+      when 404
+        return failure(worker_gone(id)) if reply.json&.dig("error") == "unknown_session"
+
+        cant = options[:dismiss] ? "dismiss a question" : "take an answer"
+        failure(BridgeClient.stale_worker_message(id, cant: cant))
+      else failure("the worker answered #{reply.status}: #{reply.json&.dig("detail") || reply.body}")
+      end
+    rescue Errno::ETIMEDOUT
+      failure("the worker did not take the answer in time; the question is still open: try again")
+    rescue SystemCallError, IOError, SocketError
+      failure(worker_gone(id))
+    end
+
+    # The question was answered elsewhere (the web first), or another one
+    # waits now: said, then what comes next is waited for.
+    # @return [nil]
+    def not_open(qid)
+      error_line("#{command_name}: question #{qid} is no longer open; not answered here, waiting for what comes next")
+      nil
+    end
+
+    def worker_gone(id)
+      "the worker is gone and the question with it; send the task again: chi send --wait -m \"…\" #{id}"
+    end
+
+    # @return [Integer] 1, after the line
+    def failure(line)
+      error_line("#{command_name}: #{line}")
+      1
+    end
+
+    # The Bridge refused the answer itself (an option not offered, two on a
+    # single-select question): a usage error, the question still open.
+    def usage_failure(line)
+      error_line("#{command_name}: #{line}")
+      CLI::Exit::USAGE
+    end
+  end
+end

data/lib/samagotchi/bridge.rb

@@ -18,6 +18,7 @@ require_relative "bridge/sse_writer"
 require_relative "bridge/turn_accumulator"
 require_relative "session"
 require_relative "engine"
+require_relative "guardrails/parent_approvals"
 require_relative "session_commands"
 require_relative "image_store"
 require_relative "log"
@@ -496,6 +497,10 @@ module Samagotchi
       qid = fetched(parsed, "id")
       selected = fetched(parsed, "selected")
       freeform = fetched(parsed, "freeform")
+      # chi answer's marker: a parent agent, held to this worker's
+      # guardrails.parent_approvals (QuestionDesk::Refused). Not a boundary:
+      # any local process may post here, with or without it.
+      client_id = fetched(parsed, "client_id")
       if qid.to_s.strip.empty?
         return [{ "Allow" => "POST" }, 400, { error: "missing_fields", detail: "id required" }]
       end
@@ -504,11 +509,15 @@ module Samagotchi
       return deadline_passed("answer") if expired?("answer_expired", deadline, sid: session_id, id: qid)
 
       begin
-        result = @engine.answer_question(id: qid, selected: selected, freeform: freeform)
+        result = @engine.answer_question(id: qid, selected: selected, freeform: freeform, client_id: client_id)
         [{}, 200, { status: "answered", session_id: session_id, answer: result }]
       rescue Engine::QuestionNotPending => e
         # Another client answered first, or the question was cancelled.
         [{}, 409, { error: "question_not_pending", detail: e.message }]
+      rescue QuestionDesk::Refused => e
+        Log.info(:bridge, "parent_approval_refused", sid: session_id, id: qid, reason: e.reason)
+        [{}, 403, { error: "parent_approval_refused",
+                    detail: Guardrails::ParentApprovals.message(e.reason) }]
       rescue ArgumentError => e
         [{}, 400, { error: "invalid_answer", detail: e.message }]
       end
@@ -888,6 +897,7 @@ module Samagotchi
       202 => "Accepted",
       204 => "No Content",
       400 => "Bad Request",
+      403 => "Forbidden",
       404 => "Not Found",
       409 => "Conflict",
       500 => "Internal Server Error",

data/lib/samagotchi/bridge_client.rb

@@ -108,10 +108,15 @@ module Samagotchi
 
     # POST /session/:id/answer. 200 = recorded, 409 = another client answered
     # first (or the question is gone), 400 = invalid selection, 408
-    # deadline_passed = read too late and dropped (see DEADLINE_SHARE).
+    # deadline_passed = read too late and dropped (see DEADLINE_SHARE), 403
+    # parent_approval_refused = a parent's allow (client_id cli:answer)
+    # beyond the worker's guardrails.parent_approvals.
+    # @param client_id [String, nil] who answers (chi answer marks its own)
     # @return [Response]
-    def answer(id:, selected:, freeform: nil)
-      post("answer", { id: id, selected: selected, freeform: freeform, deadline: deadline }, read_body: true)
+    def answer(id:, selected:, freeform: nil, client_id: nil)
+      body = { id: id, selected: selected, freeform: freeform, deadline: deadline }
+      body[:client_id] = client_id if client_id
+      post("answer", body, read_body: true)
     end
 
     # POST /session/:id/question/dismiss: leave the question unanswered.