samagotchi 0.97.0 → 0.98.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8bec4407abc70e688b17f913e574b7b7968a13941e7d2f0b2599e8ebdcdd5954
-  data.tar.gz: b1f1b5d30b31953901a94849b22da5deeb7ff97b7b57fe17bda2f3c8d40ec41b
+  metadata.gz: d683d11a3567996b7eb36801581dfa374309207bda22d8bc7d7e4e7f94d1cf2f
+  data.tar.gz: 850af6daff806f5c56e4c5b9cd2294452360c891fca2690367111ff960c721fd
 SHA512:
-  metadata.gz: 8d1d4b749231445533c0526e4fc87052294b70026ec9be742db89b474bb8bdb18079c95f67d77b8c7116f1d18d0c13be9b413eceea5e1f21343ee93925121756
-  data.tar.gz: 7d32ff1ed5d3d7fb3ccb57f304b96bdad8053671a0395db7408852b57a40130ce7fd76492a5048eba5bf7cb6ac7b94ff3b7dd0c178e536a1b9006815c10f07b9
+  metadata.gz: c2272a6357f9fe281f36078facc23678c044b1942213bd4e881881c67fbd1ad2332aaf7f55d82cbe354ab558661b6e2fa4883044d7e07897508d6518f51b3a36
+  data.tar.gz: d4e99b1672e12be69e3c36b1b5e29b9a6b3ed1e68d17a7f308e8a33d6e7a41d5790c5b2ea552c796d335e0fba94ff540d3788389b91b252d81b141ba5e38b869

data/CHANGELOG.md

@@ -8,6 +8,34 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.98.0] - 2026-10-21
+
+### Added
+
+- A long question from the model gets room in the web stage: when its reply doesn't fit, the stage grows (up to 85%
+  of the panel) for the turn, the reply reads from its start in one scroll, and an "Answer ↓" pill leads to the card
+  while it is out of view. Approvals, the step limit and hooks' questions keep their layout.
+- A new hook event, `:question_asked`, lets a plugin attach refs to the reply that asks a question or an approval
+  (display only, never in the prompt); the web pairs them in the asking text, on the card and in the history step.
+  A bundle manifest's hook can list `events: [...]` to run one hook for several events. See
+  [docs/hooks.md](docs/hooks.md).
+- source-links 0.6.0 links the issue keys and paths in a waiting question's reply too, not only in answers.
+
+### Changed
+
+- The web's rename ✎ moved from the info bar to the session's title: on the active card and next to the title in
+  the top bar, with the input over the title.
+- A model server's 404 that lists its models puts `did you mean …?` ahead of the (cut) list, and names up to three
+  ids: every nearest typo on a tie, or the listed ids that contain the name asked for (`Qwen3.6-35B` →
+  `mlx-community--Qwen3.6-35B-A3B-4bit` or `…-8bit`).
+
+### Fixed
+
+- A Gemma 4 step on the native loop no longer shows its tool call's body (`call:ask_user_question{…}`) as text in
+  the web history after a reload.
+
+Update with `chi update` (the system bundle 0.98.0, source-links 0.6.0, the dev profile 0.7.1), then restart `chi web`.
+
 ## [0.97.0] - 2026-10-21
 
 ### Added
@@ -3727,7 +3755,8 @@ and long-lived sessions.
 - A macOS desktop helper (`chi desktop install`): a "Send to chi" Service and a
   hotkey panel that send selected text or the clipboard to your sessions.
 
-[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.97.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.98.0...HEAD
+[0.98.0]: https://github.com/dm1try/samagotchi/compare/v0.97.0...v0.98.0
 [0.97.0]: https://github.com/dm1try/samagotchi/compare/v0.96.0...v0.97.0
 [0.96.0]: https://github.com/dm1try/samagotchi/compare/v0.95.0...v0.96.0
 [0.95.0]: https://github.com/dm1try/samagotchi/compare/v0.94.0...v0.95.0

data/docs/architecture.md

@@ -421,7 +421,14 @@ The page's frequent reads of `GET /api/sessions/:id` stay light too:
   finishes the ended turn's own line by its `turn_id` (sent as `&turn_id=`, which also picks that
   turn's answer). A tail read's timing is always the newest turn's; `recent=1` is accepted and not needed.
   The page binds an answer's `display_refs` to its bubble (`answer_refs.js`: on a reload's render and on this
-  read's re-render) and pairs them with the bubble's links and text before the `path:line` scan. A file ref outside the
+  read's re-render) and pairs them with the bubble's links and text before the `path:line` scan. A question's
+  refs (`pending_question.refs`, `:question_asked`) pair the same way (`markdown_place.js` `linkRefsIn`/`pairRefsIn`):
+  `question_requested` (or a snapshot's pending question) keeps them on the asking step's gen
+  (`turn_model.js` `questionRefs`) before the card draws, so the stage's asking slot (`stage_slots.js`
+  `drawAsking(text, refs)`) pairs them on its raw draw and again after its markdown swap; the card pairs its
+  question text and its kept reply (`question_cards.js`); the step's closed `.gen-text` takes them
+  (`turn_view.js`; on a reload its `data-answer-at`, the message's `display_refs`) and `linkTextRefs` pairs it at
+  the turn's end and after a reload. A file ref outside the
   session's folder is dropped, as a reload drops it: the folder `/tail` names, else (an older worker) the hub's
   session list entry's, else (refs to check, no hub entry) the session file's; with no folder known at all, every
   file ref is dropped rather than shown unchecked.
@@ -507,7 +514,8 @@ Bridge's stream above): the chat loop's thinking is the
 server's `reasoning_content`; the raw-prompt loop splits each generation's
 stream with a fresh `ThoughtStreamSplitter`, seeded with the prompt's prefill (Qwen's `<think>` and Gemma's
 `<|channel>thought … <channel|>` are thinking, tool-call bodies are dropped
-from `text:`). The chat loop's model turns keep their `tool_calls` and tool results their `tool_call_id`,
+from `text:`; a saved step's text, as the web history and the attached terminal's join show it,
+drops both too: `OutputFormatter.strip_markup`). The chat loop's model turns keep their `tool_calls` and tool results their `tool_call_id`,
 so later requests and resumed sessions pair them, and their reasoning (`thinking:`), which goes back as
 `reasoning_content` on the running turn's replies (`reasoning_history`; a step-limit Continue's
 turn goes on from the run it resumes, `reasoning_since:`). It has its own system prompt

data/docs/bundle-authoring.md

@@ -51,7 +51,8 @@ plugin:
   sha256: sha256:<hex>       # `chi bundle check --fix` fills it; never compute it by hand
 # files:                     # memories it installs (top-level *.md); without files: every *.md but README & co.
 #   my_notes.md: sha256:<hex>
-# hooks:                     # hooks/*.rb files (a plugin's chi.on is usually simpler)
+# hooks:                     # hooks/*.rb files (a plugin's chi.on is usually simpler), each with event: NAME
+#                            # or events: [a, b] (one instance for both; chi newer than 0.97.0)
 # needs: [gh]                # outside commands it relies on
 ```
 
@@ -64,7 +65,7 @@ time. `chi bundle check --set KEY=VALUE` gives the sandboxed load a setting.
 ## What a hook sees
 
 `chi.on(event) { |event, ctx| … }` gets a Hash. The events, in a turn's order: `session_start`, `before_turn`,
-`before_generation`, `generation_progress`, `after_generation`, `before_tool_call`, `after_tool_call`,
+`before_generation`, `generation_progress`, `after_generation`, `before_tool_call`, `question_asked`, `after_tool_call`,
 `after_turn`, `session_end` (the fields of each: [hooks.md, Hook Events](hooks.md#hook-events)). A symbol not in
 that list is never fired (`check` warns). The two a bundle wants most, for an `execute`:
 
@@ -116,7 +117,8 @@ end
 
 `bundle.tool_call` runs guarded hooks; `bundle.tool` calls a registered tool. `bundle.steers`, `cards`, `stops` and
 `questions` record effects; `bundle.answer` / `model_answers` provide `ask_user` / `ask_model` answers.
-`bundle.http.stub` stubs `ctx.http`; `sandbox.config`, `sandbox.fake_executable` and `bundle.install` cover setup.
+`bundle.http.stub` stubs `ctx.http`; `bundle.question_asked(text, question:)` fires `:question_asked` and returns
+the refs; `sandbox.config`, `sandbox.fake_executable` and `bundle.install` cover setup.
 The full list is in [plugins.md, Testing a bundle](plugins.md#testing-a-bundle-experimental). The kit is
 experimental (it may change before chi 1.0). If a test needs a fake of chi's own (a stub of a `Samagotchi::`
 class, a hand-built `ctx`), that is a gap in the kit: say so to the user rather than reaching into chi.

data/docs/cli.md

@@ -659,8 +659,8 @@ the first message: …)`); `/title TEXT` names the session (whitespace collapsed
 cut at 80 characters), `/title --clear` drops the name (anything after `--clear`
 is refused with the usage line). It is saved at once,
 mid-turn too, and the lists, cards, top bar and tab show it in place of the first
-message; a continue's next link keeps it. The web's info bar has `✎` for it. See
-[Session titles](sessions.md#session-titles).
+message; a continue's next link keeps it. In the web, `✎` next to the session's
+title (its strip card, or the top bar) does it. See [Session titles](sessions.md#session-titles).
 
 A `/thinking`, `/reasoning-history` or `/toolkit` change that restarts the prompt cache
 asks first: the reply says what it costs, changes nothing, and names the line
@@ -895,7 +895,12 @@ nudged the model") show ahead of those calls for about 4 s, as their rows
 wait in the closed block. A card that needs you (a question, an approval, check-in)
 sits in the stage too. While a question or approval waits, the stage shows
 the whole text of the reply that asked it (in place of its newest
-sentence) above the card, until you answer. Once answered, the model's
+sentence) above the card, until you answer. A long reply that asks the
+model's own question (one that doesn't fit that slot) gets more room: the
+stage grows to about 85% of the page for the rest of the turn (never above
+the session panel), the reply reads from its start in the stage's one
+scroll, and while the card is out of view a `❓ Answer ↓` pill at the
+stage's bottom edge takes you to it. Once answered, the model's
 question or its own approval keeps that reply (a delegate's relayed
 approval, a hook's question and the step limit don't): two muted lines
 under its `question → answer` line, the whole text when you open the card,

data/docs/hooks.md

@@ -56,6 +56,7 @@ The plugin class must respond to `#call(event)` — duck-typed, no base class re
 | `: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, restarted: true (only on the first fire after a dropped stream was asked again) }` |
 | `: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 }` |
+| `:question_asked` | A question of the model's own (`ask_user_question`) or an approval of its tool call is about to open, on the turn's thread (not a hook's or plugin's `ask_user`, a relayed delegate approval, the step-limit question, a `--non-interactive` run or a stored approval: none of those fire it) | `{ type: :question_asked, kind: "question" \| "approval", text: "..." (the reply that asks, as the asking slot shows it: no thoughts, no tool-call markup), question: {...} (the question's fields, frozen: question/options/header…, an approval's approval: facts too; no id yet), refs: (see [Refs on a question](#refs-on-a-question-display-only)) }` |
 | `:after_tool_call` | After tool execution | `{ type: :after_tool_call, iteration: N, tool: "read", output: "..." (the text the model gets: capped at max_tool_output_chars; a cut one has a [cut: …] line, at its end, or for an execute result between its head and its tail, the whole output saved in the session's tool_output/ folder), status: "ok" \| "error" \| "blocked" \| "stopped", call: {...} (the call that ran, as the gate left it), elapsed_ms: N (the tool's own run, without an approval wait; nil for a denied call), result: "..." (the tool's own text: no "[read]" lead, no "ran as:" line, never cut) }`; `stopped` is a `task_wait` the turn's Stop ended (the task runs on) or whose task was stopped. Match on `result:`, not `output:`: it is what the tool said (`Error: command timed out after 120s` for an execute killed at its limit in kill mode, `Samagotchi::Tools::Execute::TIMEOUT_PREFIX`; `Still running at the 120s limit: …` for one handed over as a task, `Samagotchi::Tools::Execute::HANDED_OVER`) |
 | `:session_end` | After each turn `:after_turn` fires for, after it (turn-level lifecycle) | `{ type: :session_end, session_id: "..." }` |
 
@@ -366,6 +367,58 @@ end
 
 A plugin gets the same from `chi.on(:after_turn) { |event, ctx| event[:refs].call(…) }`.
 
+## Refs on a question (display only)
+
+`:question_asked` carries `refs:` too, for the reply that asks the question: a
+ticket the model names while it asks is a ref while the question waits, when
+the user needs it.
+
+```ruby
+class JiraQuestionRefs
+  def call(event)
+    return unless event[:type] == :question_asked
+
+    event[:text].scan(/\b[A-Z][A-Z0-9]+-\d+\b/).uniq.each do |key|
+      event[:refs].call(match: key, kind: "issue", target: { id: key }, label: key,
+                        actions: [{ id: "open", label: "Open in Jira", url: "https://jira.example.com/browse/#{key}" }])
+    end
+  end
+end
+```
+
+- The call, its return values, the checks and the `refs_rejected` log are
+  [Refs on the answer](#refs-on-the-answer-display-only)'s, with lower caps:
+  50 refs and 32 KiB per step. `nil`: the turn has no model step to attach to,
+  or the call came after the hooks ran.
+- They are kept as `display_refs` on the step's model message (the one that
+  asks; in the session file after the turn, a cancelled one too) and go on the
+  pending question as its `refs` (the `question_requested` event, the session
+  file while it waits, the saved question card). A second question in the same
+  step adds to the step's list, and its pending question has the whole list.
+  The model never sees them.
+- The web checks them again wherever a saved one reaches it (the pending
+  question, a saved card, the history), as an answer's, and pairs them as an
+  answer's (the three passes above) in: the stage's asking slot while the
+  question waits (its raw text, then again once its markdown is in), the
+  card's question text, the answered card's kept reply (raw, then its
+  markdown when opened; never its one-line summary copy), and that step's
+  text in the history, live (at the turn's end) and after a reload. A ref
+  whose `match` is only in the question's text pairs there alone; the step's
+  text drops it. **Terminals** ignore them.
+- **Its time is the question's wait**: the hooks run before the question
+  opens, so a slow one delays it (and counts in `ask_user_question`'s
+  `elapsed_ms` and an approval's `waited_ms`). A hook that raises is logged and
+  the question opens with the other hooks' refs. With no hook on the event
+  nothing is built.
+- Don't ask from it: `event[:ask_user]` (and `ctx.ask_user` in a `chi.on`
+  block) returns nil at once here.
+- Needs chi newer than 0.97.0: set `requires_chi`.
+
+A plugin gets the same from `chi.on(:question_asked) { |event, ctx| event[:refs].call(…) }`. The bundle test
+kit fires it as chi does: `bundle.question_asked(text, kind:, question:)` returns the refs the step gets
+([plugins.md](plugins.md#testing-a-bundle-experimental)). The shipped source-links bundle subscribes (its
+sources' refs in the reply that asks, and in the question's text and options).
+
 ## Settings
 
 A hook class whose `initialize` takes an argument gets its settings: **one
@@ -599,6 +652,12 @@ Notes:
 
 - Hook key = basename (flat under `hooks/`). No subdirs in v1.
 - `event` is required for auto-registration; a hook with no event is skipped.
+- `events: [after_turn, question_asked]` (a list, in place of `event:`) registers the hook for each event it
+  names: **one** instance serves them all (its state is shared), and `#call` tells them apart by
+  `event[:type]`. `event:` and `events:` together, or an `events:` that isn't a non-empty list of event names,
+  is refused at install (`hooks: <file>: …`). `on_error: fail_closed` applies to its `before_tool_call`
+  registration only. Needs chi newer than 0.97.0 (an older chi installs the hook with no event and never loads
+  it): set `requires_chi`.
 - `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.

data/docs/internals/bundles.md

@@ -37,7 +37,7 @@ user-facing side (what a bundle owns, profiles, needs) is in [memory.md](../memo
 | `AssetInstaller` | the parts that live in `.bundles/<name>/`: hooks, guardrail rules, plugin, scripts; returns `AssetInstaller::Installed` (the paths the record keeps) |
 | `Merger` | 3-way classification per file: `install`, `fast_forward`, `keep`, `noop`, `conflict` |
 | `Provenance` | the `.bundles/<name>/` dir: `#write` the record + bases, `#record` → `InstalledBundle`, `.each_installed`, `.claimants` (which bundles own a file) |
-| `InstalledBundle`, `BundleHook`, `PluginRef` | value objects for the record; tolerant of older records (missing keys read as empty) |
+| `InstalledBundle`, `BundleHook`, `PluginRef` | value objects for the record; tolerant of older records (missing keys read as empty). `BundleHook#events` is the manifest's `event:` or its `events:` list (written back as `event:` for one, as an older chi reads it); `Hooks::BundleLoader#load_hook_file` builds the hook once and registers it under each |
 | `Builder` | `chi bundle build`: memories (+ the installed bundle's hooks, rules, plugin, scripts) → zip/tar/dir |
 | `Profile` | meta bundles (`includes:`): install the members, record which; `InstallResult#kept_own` names a new member's memory files the user already had, with other bytes (`kept_own_line`, printed by `chi bundle`, `chi update` and `chi bootstrap`); a dry run runs each member's Installer as a dry run too, so it names them as well |
 | `SystemBundle`, `ShippedUpdate` | the built-in system bundle (`ensure!` at Engine start, `sync` in `chi update`) and `chi update`'s upgrade of shipped bundles; both drive the Installer with `upgrade: true` |

data/docs/internals/engine.md

@@ -594,6 +594,23 @@ logged). Both are display only: `AnswerDisplay::DISPLAY_ONLY` lists `display`, `
 after_generation), while `KernelLoop#sanitize_history` and `ChatLoop#plain` copy them so the stored conversation keeps
 them across turns. `Web::App#messages_for_display` sends `display_refs` re-validated (`AnswerRefs.for_display`).
 
+`:question_asked` (`QuestionAsked`, `question_asked.rb`) fires from the two Engine seams where a question of the
+model's opens, never from `QuestionDesk`: `Engine#request_question` (the kernel's `question_handler`, after
+`AskUserQuestion.validate`; not with `interface == :non_interactive`) and the guardrail wiring's `ask:` lambda
+(`GuardrailWiring#request_approval`, after a stored approval and the non-interactive deny). So `ask_for_hook`, a
+relayed approval (`EnginePeers#open_question` → `Engine#open_question`) and `post` (the step-limit question) never
+fire it. `QuestionAsked.fire` is a no-op without a subscriber (`Registry#any?`); else it finds the live
+conversation's last `role: "model"` entry (`Engine#live_conversation`, one lookup for both loops: a ChatLoop batch may
+end in a tool result), builds an `AnswerRefs` on that step alone with the question caps (50 / 32 KiB), fires with the
+step's text (`Engine#question_step_text`: the parser's thought and tool-call strip, then
+`OutputFormatter.strip_markup`), a frozen copy of the fields and a no-op `ask_user`, then sets `display_refs` on
+the step **in place** under the event lock (the loops and the forget layer hold entries by identity) and returns the
+fields with `refs:`. `QuestionDesk#request` forwards `refs` past its slice; `PendingQuestion#refs` carries them to
+`:question_requested`, the session file and the cards. `Web::App#with_question_refs` re-validates them (the pending
+question, `cards_for_display`) with the same caps; the page pairs them in the asking slot, on the card and on the
+step's text ([architecture.md](../architecture.md), the `display_refs` paragraph). The kit's
+`Testing::Bundle#question_asked` calls `QuestionAsked.fire` with a one-step conversation.
+
 ### Hook lifecycle
 
 - **Bundle hooks** (`Registry#register_bundle`) and **config hooks** (`register_persistent`, from config.yml)
@@ -756,6 +773,7 @@ Paths are under `lib/samagotchi/`.
 | `toolkit_binding.rb` | `ToolkitBinding`: the Engine's toolkit seam (the kits, `#explained`, `ctx.use_toolkit`, the turn-start `#apply!` behind `Engine#apply_toolkit!`) |
 | `hooks/registry.rb` | Hook registry, fire order, `Hooks::Runtime` |
 | `hook_routes.rb` | `HookRoutes`: the Engine's routes for a hook's or plugin's notice (`:hook_notice`, `fallback_for:`), question, stop and steer, and the guardrails' after-load line |
+| `question_asked.rb` | `QuestionAsked`: the `:question_asked` fire, the asking step's refs (`display_refs` in place, the pending question's `refs`) |
 | `question_desk.rb`, `pending_question.rb`, `question_answer.rb` | `QuestionDesk`: the one open question (ask, post, answer, cancel, relay mark); `PendingQuestion` and `QuestionAnswer`, its values (Hashes only in events, Bridge JSON, the session file and the hook/plugin `ask_user` result) |
 | `hook_question.rb` | `HookQuestion`: a hook's or plugin's `ask_user` question as one value, from the runtime/host edge to `QuestionDesk#ask_for_hook` |
 | `event_routes.rb` | `EventRoutes`: where a card (`Engine#show_card`), a notice (`HookRoutes#notify`) and a guardrails line (`#guardrail_notify`, turn or between turns only) go: held while the plugins load, an anytime command's, an init task's, a running turn's event, else announced or held for `holding_announcements` |

data/docs/plugins.md

@@ -433,7 +433,9 @@ This is a bundle hook, the same as a `hooks/*.rb` file. See
 [hooks.md](hooks.md#hook-events) for the events; on `:after_turn`,
 `event[:present]` sets how the answer is shown in the web
 ([Presenting the answer](hooks.md#presenting-the-answer-display-only)) and `event[:refs]`
-attaches refs to it ([Refs on the answer](hooks.md#refs-on-the-answer-display-only)). Its label is
+attaches refs to it ([Refs on the answer](hooks.md#refs-on-the-answer-display-only)); on
+`:question_asked`, `event[:refs]` attaches refs to the reply that asks a question
+([Refs on a question](hooks.md#refs-on-a-question-display-only)). Its label is
 `plugin.rb (bundle my-bundle)`. The block may take only the event. If it
 raises, the error is logged and the hook is skipped.
 
@@ -1159,6 +1161,7 @@ require "samagotchi/testing"
 bundle = Samagotchi::Testing::Bundle.load("path/to/my-bundle", settings: { "every" => 3 },
                                           host: { session_id: "s1", cwd: Dir.pwd })
 bundle.fire(:after_turn, status: "completed")            # → the event, after the hooks
+bundle.question_asked("Fix JIRA-1?", question: { question: "Go?" })   # → the refs, as chi's seams fire it
 event = bundle.before_tool_call_event({ name: "read", path: "a.txt" }, params: "read a.txt")
 bundle.command("/mine stop")                             # → what the command returned
 bundle.tool("my_tool", path: "a.txt")                    # → the text the model reads
@@ -1212,6 +1215,10 @@ bundle.shutdown
   lays them over `settings:` through chi's own `Context#settings`; the plugin's `initialize(settings)` gets
   `settings:` only. `bundle.set(session_settings:)` moves the session to a new id (`test-session-2`, or the
   `session_id:` given beside it): chi never changes them within a session, and builds `ctx.settings` once per id.
+- **`question_asked(text, kind: "question", question: {}, cwd: nil)`** fires `:question_asked` through
+  `QuestionAsked.fire`, as chi's two seams do: a step whose text is `text` asks a question (or `kind: "approval"`)
+  with the `question` fields, and the refs the hooks attach come back checked (the question caps, a file ref under
+  `cwd:`, default the session's folder), as the step and its pending question keep them; `[]` for none.
 - **A hook that raises fails the call** (`Testing::HookFailed`, with the hook's error) where chi would log it and
   go on; `bundle.lenient { … }` collects them in `bundle.errors` instead.
 - **Sandbox.** A test runs with temp config, state, data and cache homes (config.yml, memories, `ctx.data_dir`, the

data/docs/sessions.md

@@ -221,7 +221,7 @@ chi send --new --continues last:3fa2 -m "new day"      # the next link of 3fa2's
 
 A session is named by its first message until you give it a title: `/title Coordinator` (in the REPL, an attached terminal, the web composer or `chi send -m "/title Coordinator" ID`; a parent agent may name its delegates the same way). The title is saved in the session file (`title`), whitespace collapsed and cut at 80 characters, and runs mid-turn too, at once. `/title` alone shows it (`title: none (shows the first message: hey chi …)` without one); `/title --clear` drops it, and the first message names the session again. A session whose first line was the command itself (`chi send --new -m "/title X"`) takes its preview from its first real message.
 
-The title names the session wherever its first message did: `chi sessions list` (plain, `--live`, tsv and json's `desc`, before the recap; json has `title` too), `chi sessions delete`'s line, the `list_sessions` tool, `chi broadcast`, the desktop helper, a parent's children (the coordinator bundle's `/children` card, `ctx.sessions.children`; `ctx.sessions.read` too), and in the web the cards, the families and chain rows, the top bar and the browser tab, the notifications and the search; the terminal's status row too (the REPL's and an attached one's, first, see [Status Line](cli.md#status-line)). The web's info bar has `✎` (Rename this session): a small input prefilled with the title; Enter or a click elsewhere sends `/title TEXT` when it changed (empty: `/title --clear`), Esc closes it unsent. A session a chi REPL owns has no `✎`. A continue's new link keeps the title (see [Session chains](#session-chains)). An older `chi web` (or any chi from before the field) that saves a session drops its title: restart `chi web` after upgrading.
+The title names the session wherever its first message did: `chi sessions list` (plain, `--live`, tsv and json's `desc`, before the recap; json has `title` too), `chi sessions delete`'s line, the `list_sessions` tool, `chi broadcast`, the desktop helper, a parent's children (the coordinator bundle's `/children` card, `ctx.sessions.children`; `ctx.sessions.read` too), and in the web the cards, the families and chain rows, the top bar and the browser tab, the notifications and the search; the terminal's status row too (the REPL's and an attached one's, first, see [Status Line](cli.md#status-line)). In the web, `✎` (Rename this session) sits next to the session's title, on its active strip card or after the top bar's title: a small input over the title, prefilled with it; Enter or a click elsewhere sends `/title TEXT` when it changed (empty: `/title --clear`), Esc closes it unsent, and so does the title leaving the screen (All sessions opened, the card swiped out of a phone's strip). A session a chi REPL owns has no `✎`, nor one that shows no title yet (`/title` still works from the composer). A continue's new link keeps the title (see [Session chains](#session-chains)). An older `chi web` (or any chi from before the field) that saves a session drops its title: restart `chi web` after upgrading.
 
 ## Session chains
 

data/lib/samagotchi/answer_refs.rb

@@ -52,7 +52,9 @@ module Samagotchi
   #
   # The target is AnswerDisplay's: the stored conversation's last message
   # when it is the model's. The list starts from the refs it already has
-  # (re-validated), so a later hook run never loses them.
+  # (re-validated), so a later hook run never loses them. QuestionAsked
+  # uses it too, on the step that asks a question (+messages+ that one
+  # step, lower caps).
   class AnswerRefs
     KEY = :display_refs
     MAX_REFS = 200
@@ -63,12 +65,13 @@ module Samagotchi
     # rebuilt and checked again, the caps applied; what isn't valid any
     # more is dropped. Never raises: a reload must show the conversation.
     # A relative file path is dropped (it was stored absolute), and with
-    # +cwd+ (the session's folder) a file outside it.
+    # +cwd+ (the session's folder) a file outside it. +max_refs+ and
+    # +max_bytes+: the caps (a question's are lower, QuestionAsked).
     # @return [Array<Hash>] the refs to send ({match:, kind:, target:, …})
-    def self.for_display(raw, cwd: nil)
+    def self.for_display(raw, cwd: nil, max_refs: MAX_REFS, max_bytes: MAX_BYTES)
       return [] if raw.nil?
 
-      kept = new([{ role: "model", KEY => raw }], cwd: cwd).to_a
+      kept = new([{ role: "model", KEY => raw }], cwd: cwd, max_refs: max_refs, max_bytes: max_bytes).to_a
       dropped = raw.is_a?(Array) ? raw.length - kept.length : 1
       Log.debug(:web, "display_refs_dropped", count: dropped) if dropped.positive?
       kept
@@ -81,10 +84,14 @@ module Samagotchi
 
     # @param messages [Array<Hash>] the conversation the turn stored
     # @param cwd [String, nil] the session's folder, for relative file paths
-    def initialize(messages, cwd:)
+    # @param max_refs [Integer] the list's cap in refs
+    # @param max_bytes [Integer] the list's cap in JSON bytes
+    def initialize(messages, cwd:, max_refs: MAX_REFS, max_bytes: MAX_BYTES)
       last = Array(messages).last
       @target = last if last.is_a?(Hash) && (last[:role] || last["role"]).to_s == "model"
       @roots = RowRefs.roots(cwd)
+      @max_refs = max_refs
+      @max_bytes = max_bytes
       @refs = []
       @seen = {}
       @bytes = 2 # the list's []
@@ -143,10 +150,10 @@ module Samagotchi
 
       entry = AnswerRef.from(value, roots: @roots).to_h
       return true if @seen.key?(entry)
-      return over_cap(hook, "#{MAX_REFS} refs") if @refs.length >= MAX_REFS
+      return over_cap(hook, "#{@max_refs} refs") if @refs.length >= @max_refs
 
       size = JSON.generate(entry).bytesize + (@refs.empty? ? 0 : 1)
-      return over_cap(hook, "#{MAX_BYTES / 1024} KiB") if @bytes + size > MAX_BYTES
+      return over_cap(hook, "#{@max_bytes / 1024} KiB") if @bytes + size > @max_bytes
 
       push(entry, size)
       @added = true
@@ -160,10 +167,10 @@ module Samagotchi
     # @return [Boolean] kept
     def keep(raw)
       entry = AnswerRef.from(raw, roots: @roots, relative: false).to_h
-      return false if @seen.key?(entry) || @refs.length >= MAX_REFS
+      return false if @seen.key?(entry) || @refs.length >= @max_refs
 
       size = JSON.generate(entry).bytesize + (@refs.empty? ? 0 : 1)
-      return false if @bytes + size > MAX_BYTES
+      return false if @bytes + size > @max_bytes
 
       push(entry, size)
       true

data/lib/samagotchi/bundle_command.rb

@@ -476,7 +476,7 @@ module Samagotchi
           hooks.each do |hk, hook|
             hook_path = File.join(Samagotchi::MemoryBundle::Provenance.new(name: name).hooks_dir, hk)
             exists = File.exist?(hook_path) ? "ok" : "missing"
-            @stdout.puts "    #{hk}: event=#{hook.event} on_error=#{hook.on_error} priority=#{hook.priority} [#{exists}]"
+            @stdout.puts "    #{hk}: #{hook.events_field} on_error=#{hook.on_error} priority=#{hook.priority} [#{exists}]"
           end
           @stdout.puts "    requires_chi: #{st[:provenance].requires_chi}" if st[:hooks_requires_failure]
           @stdout.puts "    not loaded: #{st[:hooks_requires_failure]}" if st[:hooks_requires_failure]
@@ -658,7 +658,7 @@ module Samagotchi
     end
 
     def hook_metadata_line(hook)
-      "--- metadata: event=#{hook.event} on_error=#{hook.on_error} priority=#{hook.priority} sha256=#{hook.sha256}"
+      "--- metadata: #{hook.events_field} on_error=#{hook.on_error} priority=#{hook.priority} sha256=#{hook.sha256}"
     end
 
     def build(rest)

data/lib/samagotchi/bundles/dev/manifest.yml

@@ -1,10 +1,10 @@
 ---
 name: dev
-version: 0.7.0
+version: 0.7.1
 scope: system
 description: "Developer tools"
 trust_level: reviewed
-requires_chi: ">= 0.72.0"
+requires_chi: ">= 0.98.0"
 includes:
 - known-names
 - mcp

data/lib/samagotchi/bundles/source-links/hooks/source_links.rb

@@ -4,8 +4,8 @@
 require "open3"
 require "samagotchi/ref"
 
-# An after_turn hook that links the source refs the model's answer
-# mentions — a JIRA ticket, a GitHub issue, an internal wiki page. In the
+# An after_turn (and question_asked) hook that links the source refs the
+# model's answer mentions — a JIRA ticket, a GitHub issue, an internal wiki page. In the
 # web, each ref in the answer becomes a link (`[JIRA-123](https://…)`,
 # through event[:present]: display only, the model's text stays as it was,
 # and it survives a reload). Every UI also gets one line right after the
@@ -58,6 +58,14 @@ require "samagotchi/ref"
 # action, "Open in <name>", the ref's URL. A URL that isn't http(s) stays a
 # markdown link only. The web's ref menu shows the action.
 #
+# The hook is on :question_asked too (the manifest's events:, chi newer than
+# 0.97.0): while a question of the model's (or an approval of its call)
+# waits, the refs in the reply that asks it, and in the question's text and
+# options, are refs on that reply, the same as an answer's. The web pairs
+# them in the stage's asking slot, on the question's card and on that step
+# in the history (a ref only in the question's text pairs there alone). No
+# links in the text and no note line for it: the turn's end has those.
+#
 # The note is not stored in the conversation: it is an event, replayed by a
 # UI with the session's cards (a reload keeps it, after the worker stopped
 # too: cards.json). The links are stored as the answer's display. A ref in
@@ -120,10 +128,20 @@ class SourceLinks
   end
 
   def call(event)
-    return unless event.is_a?(Hash) && event[:type] == :after_turn
-    return unless event[:status].to_s == "completed"
+    return unless event.is_a?(Hash)
     return if @sources.empty?
 
+    case event[:type]
+    when :after_turn then after_turn(event)
+    when :question_asked then question_asked(event)
+    end
+  end
+
+  private
+
+  def after_turn(event)
+    return unless event[:status].to_s == "completed"
+
     text = last_model_text(event[:messages])
     return if text.nil? || text.empty?
 
@@ -141,7 +159,23 @@ class SourceLinks
     event[:notify]&.call(line(found), level: :info, fallback_for: covered ? :display : nil)
   end
 
-  private
+  # A question of the model's (or an approval of its call) is about to
+  # open: the refs in the reply that asks it and in the question's own text
+  # and options, each scanned on its own (a code span never runs from one
+  # into the next), as refs on that reply. No present (a mid-turn text has
+  # no display) and no note line (the after-turn one stays the terminals').
+  def question_asked(event)
+    refs = event[:refs]
+    return unless refs
+
+    question = event[:question].is_a?(Hash) ? event[:question] : {}
+    field = ->(key) { question.key?(key) ? question[key] : question[key.to_s] }
+    parts = [event[:text], field.call(:question), *Array(field.call(:options))]
+    parts.each do |part|
+      text = part.is_a?(String) ? part : ""
+      add_refs(refs, occurrences(text[0, MAX_SCAN])) unless text.empty?
+    end
+  end
 
   # Links the refs in the answer as shown: the model's text unless an
   # earlier hook changed it (then its offsets differ, so it is scanned

data/lib/samagotchi/bundles/source-links/manifest.yml

@@ -1,15 +1,15 @@
 ---
 name: source-links
-version: 0.5.1
+version: 0.6.0
 scope: system
-description: Links source refs (JIRA tickets, GitHub issues, …) in the model's answer — inline links in the web, and a one-line note after the turn (note false turns it off); sources are configured patterns
+description: Links source refs (JIRA tickets, GitHub issues, …) in the model's answer — inline links in the web, refs in a waiting question's reply, and a one-line note after the turn (note false turns it off); sources are configured patterns
 trust_level: reviewed
-requires_chi: ">= 0.61.0"
+requires_chi: ">= 0.98.0"
 files:
   source_links.md: sha256:ace01a0f7c308a0ae54ece714c31c0e6d7a49c372d98111030e6d268320bed3a
 hooks:
   source_links.rb:
-    sha256: sha256:c41249ec0bbb708ec7827e1d0f66689dfbbc415c1da5fe33f5d3a8ec8e5eaa2f
-    event: after_turn
+    sha256: sha256:84c0bef064fb1ea76749a61e758eba612662aaf0f05f18a18ab4228497078fa2
+    events: [after_turn, question_asked]
     on_error: log
     priority: 90

data/lib/samagotchi/bundles/system/manifest.yml

@@ -1,6 +1,6 @@
 ---
 name: samagotchi-system
-version: 0.97.0
+version: 0.98.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:

data/lib/samagotchi/engine.rb

@@ -77,6 +77,7 @@ require_relative "answer_display"
 require_relative "answer_refs"
 require_relative "edit_preview"
 require_relative "question_desk"
+require_relative "question_asked"
 require_relative "child_reports"
 require_relative "relay_desk"
 require_relative "guardrail_wiring"
@@ -364,7 +365,8 @@ module Samagotchi
         model_key: -> { @model_key },
         model_name: -> { guardrail_model_name },
         cancelled: -> { !!active_cancel_controller&.cancelled? },
-        ask: ->(fields) { open_question(fields) },
+        # An approval of the model's call: :question_asked first (QuestionAsked).
+        ask: ->(fields) { open_question(question_asked(QuestionAsked::KIND_APPROVAL, fields)) },
         notify: ->(message) { guardrail_notify(message) }
       )
     end
@@ -1576,13 +1578,35 @@ module Samagotchi
 
     # Ask the model's question (ask_user_question): the kernel's
     # question_handler, called on the turn thread with the payload
-    # Tools::AskUserQuestion.validate made (QuestionDesk#request).
+    # Tools::AskUserQuestion.validate made (QuestionDesk#request), after
+    # the :question_asked hooks (QuestionAsked) gave the step its refs; a
+    # --non-interactive run has no one to ask, so they don't fire there.
     # @param payload [Hash] {question:, options:, header:, multi_select:, allow_freeform:}
     # @return [String] normalized answer JSON
     def request_question(payload)
+      payload = question_asked(QuestionAsked::KIND_QUESTION, payload) unless interface == :non_interactive
       @question_desk.request(payload)
     end
 
+    # The :question_asked hooks for a question of the model's about to
+    # open: the fields with the asking step's refs (QuestionAsked.fire).
+    # @return [Hash]
+    def question_asked(kind, fields)
+      QuestionAsked.fire(hooks: @hooks, conversation: live_conversation, kind: kind, fields: fields,
+                         cwd: @session&.working_directory, synchronize: ->(&block) { synchronize_events(&block) },
+                         visible: ->(content) { question_step_text(content) })
+    end
+    private :question_asked
+
+    # A step's text as the asking slot shows it: the native loop's raw
+    # response without its thoughts and tool-call bodies (a chat step has
+    # neither), then the markup's tokens (OutputFormatter.strip_markup).
+    def question_step_text(content)
+      parser = @kernel.parser
+      OutputFormatter.strip_markup(parser.strip_tool_calls(parser.strip_thought(content)))
+    end
+    private :question_step_text
+
     # Open a question for the UIs and wait for its answer
     # (QuestionDesk#open_question: BLOCKS until answered or cancelled).
     # @param fields [Hash] question:, options:, header:, multi_select:, allow_freeform:, …