samagotchi 0.154.1 → 0.155.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9533994f61b5607aef4d2dc6318cd6e885a0331c163643bd06d3c16f5e6f03c0
-  data.tar.gz: b768811c50bb587fcf4d16696ab69b857c75168067fd521270d871954169874e
+  metadata.gz: 55c4e338780fd58cf97835620377051e5de8efc5c487f42bdcc9de6c3a71a5b1
+  data.tar.gz: d6f3a9f49b39b72b11a6b70c5715142ee2f54d5e6b1f94a4eb9695f3fedefd0a
 SHA512:
-  metadata.gz: 2064776b06d42184107924bc44391f46681d755437e2c98a2e7c24205e900aba33bd8d3d792c7cea4dd6bdbf2813870395112db7315dbec33f92e198267c4ddc
-  data.tar.gz: a826305fa133e9ca4d1bd62e112ca7464fcf932f91292dc4112286e7f8f501c167fc18ccfeeb12dd24bec649e24636c810a715417cac45f454a19b4ba56f2b05
+  metadata.gz: c91dd76d8d7a3bb4cc3c4432162ac91528aa8329585cc373ad6c811c68be9ff0ccf47ed12913ce19bb87edd59930ae699cf19fa5cc8128eb92f5f62cecc6624d
+  data.tar.gz: 99dd1a2761d327300d3459407c09935aa4d8f3d2826e7db5a29087013071998f0fb1e6787d520a8d19c27b0a5ec67bf64b53aa177d17fe9a003cf3dc8190aa84

data/CHANGELOG.md

@@ -8,6 +8,20 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.155.0] - 2026-11-07
+
+### Added
+
+- The inline-widgets bundle (in the `dev` profile, `chi update`): it teaches the model the `chi-ui` blocks chi web draws, so an answer that leaves you several things to decide comes with picks that fill your reply, and a "how does this work" answer with a walk you step through. The terminal shows the block's YAML; a delegate child and a `-p --non-interactive` run don't get it.
+- `chi bundle check` lists a bundle's prompt sections among what it registers.
+
+### Fixed
+
+- At the very start of a turn, a plugin's `ctx.turn_author`, a hook's `author:` and `/objectives` could still see the previous turn (its participant, its conversation); they now see the turn that just started.
+- chi web's session bar no longer slides its time and speed chips under the buttons with a long model name: the model name shortens, the buttons move to their own line together, and on a narrow window the ctx/speed/time chips get a line of their own instead of being cut off.
+
+Update with `chi update` (the dev profile 0.7.8, inline-widgets 0.1.0 new).
+
 ## [0.154.1] - 2026-11-07
 
 ### Fixed
@@ -5772,7 +5786,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.154.1...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.155.0...HEAD
+[0.155.0]: https://github.com/dm1try/samagotchi/compare/v0.154.1...v0.155.0
 [0.154.1]: https://github.com/dm1try/samagotchi/compare/v0.154.0...v0.154.1
 [0.154.0]: https://github.com/dm1try/samagotchi/compare/v0.153.0...v0.154.0
 [0.153.0]: https://github.com/dm1try/samagotchi/compare/v0.152.0...v0.153.0

data/docs/architecture.md

@@ -101,6 +101,7 @@ terminal renders the events it gets over the Bridge.
 | Core | `Samagotchi::Engine` | System prompt, memory injection, tool declarations, session lifecycle, model↔tool loop (`run_turn`). No terminal coupling. |
 | UI | `Samagotchi::TerminalUI`, `TerminalUI::AttachLauncher` / `AttachedLoop` | `TerminalUI`: the `--non-interactive` one-shot host, its own `Engine`. The attached TUI (every interactive `chi`): a client of the session worker's Bridge, no `Engine`. |
 | Model loops | `KernelLoop` (via `LLM::NativeBackend`), `LLM::ChatLoop` | The model↔tool loop: raw prompt, or a chat API (OpenAI chat, Anthropic Messages), chosen per host (see below). |
+| Turn | `TurnContext`, `TurnState`, `Engine::Turn` | One turn's frozen `TurnContext` (id, session, origin, author, participant mode, controller, folders, git facts, settings, model key/name and the tool surface (`Tools::ToolSurface`) from `generate`): built by `Engine#begin_turn`, published with the running flag by `TurnState` (the only way another thread reads the running turn: `Engine#turn_context` / `#last_turn_context`), handed explicitly down the tool path (`ModelBackend#complete(context:)`, `ToolRunner#run`, `Guardrails::Gate#evaluate`, `KernelLoop#dispatch_tool_call`). `Engine::Turn` keeps only the lifecycle state ([internals/engine.md](internals/engine.md), "Turn and TurnContext"). The turn stages (`TurnStages::ToolkitSuggestion`, `TurnStages::ContextJudge`, `TurnStages::Objectives`, `TurnStages::Warmup`, `TurnStages::VerifyAnchors`, `lib/samagotchi/turn_stages/`): the steps that keep state across the turn, built from constructor arguments and called by name from the turn's skeleton (internals/engine.md, "Turn stages"). |
 | Adapters | `Samagotchi::Client`, `LLM::OpenAIChat`, `LLM::AnthropicMessages`, `LLM::HTTP` | Raw-prompt servers, the OpenAI chat API, Anthropic's Messages API, and the HTTP they share. |
 | Tools | `lib/samagotchi/tools/*` | Execute, read, edit, write, memory, task_*, web_fetch, delegate/delegate_result, ask_user_question, reminders, send_note, list_sessions, context_read, objectives, forget_outputs, find_tools/call_tool (the tool index), plus runtime/output-guardrails. |
 | Bundles | `lib/samagotchi/memory_bundle/*`, `BundleCommand` | `chi bundle`: install/upgrade (3-way, with a text merge of edited memories), build, uninstall; the install record under `.bundles/<name>/` that the hook, guardrail and plugin loaders read ([internals/bundles.md](internals/bundles.md)). |
@@ -519,7 +520,7 @@ on every read, never kept, since config.yml and a model listing can move it with
 
 Both return an `LLM::ModelResult` and emit the same stream events; tool calls in
 both go through `ToolRunner` (events, hooks, veto, output cap) and
-`KernelLoop#dispatch_tool_call`. Every format's built-in calls (Gemma, Qwen,
+`KernelLoop#dispatch_tool_call`, given the turn's `TurnContext` as an argument. Every format's built-in calls (Gemma, Qwen,
 chat `tool_calls`) are built by one table, `Tools::BuiltinCalls`, from the
 parsed `{name, args}` (derived from `TOOL_SCHEMAS`), so a call looks the same to
 hooks and tools whichever model made it. Both loops' `generation_chunk` carries
@@ -636,7 +637,7 @@ A map of the parts the overview above doesn't name (paths under `lib/samagotchi/
 | Participants | `participants.rb` (`Participants`, the `participants.json` sidecar), `share_command.rb` (`ShareCommand`, `chi share`), `session_participants.rb`, `participants_watch.rb`, `grants.rb` (`Grants`), `participant_exposure.rb` (`ParticipantExposure`), `web/principal.rb` (`Web::Principal`), `web/participant_access.rb` (`Web::ParticipantAccess`: the participant's gate and routes), `web/participants_admin.rb` (`Web::ParticipantsAdmin`: the owner's invite, list, revoke, cap and Apply routes), `web/participant_review.rb` + `web/participant_view.rb` (`Web::ParticipantReview`, `Web::ParticipantView`), `redact.rb` (`Redact`, `Redact::Viewer`: the redaction every string a participant gets passes, also the Engine's Verify quote check), `web/participant_stream_filter.rb`, `guardrails/review_boundary.rb` + `guardrails/review_paths.rb` | The people or agents an owner invites to review one session through chi web: their grants and gate, what they read, their read-only review turns ([internals/participants.md](internals/participants.md), [guardrails.md](guardrails.md)). |
 | Analytics | `analytics_file.rb` (`AnalyticsFile`), `session_metrics/totals.rb` (`SessionMetrics::Totals`), `session_metrics/model_segment.rb` (`SessionMetrics::ModelSegment`) | A session's `analytics.json` (`SessionMetrics#persist`); the sums over its turn records (`Totals`: tokens, cost, speeds, kept as running counters) and their split per model after a `/model` switch (`ModelSegment`: a run of turns on one model, the `model_segments` rows); `session_metrics/cost.rb` (`SessionMetrics::Cost`): the spend `ctx.cost` reads; `session_metrics/usage.rb` (`SessionMetrics::Usage`): the work `ctx.usage` reads. `session_metrics/side_totals.rb` (`SessionMetrics::SideTotals`) and `side_usage.rb` (`SideUsage`): the side requests' sums, apart from the turns'. |
 | Images / vision | `image_store.rb` (`ImageStore`), `vision_support.rb`, `vision_context.rb` | Stored prompt images and whether a model takes them. |
-| Toolkits | `toolkit.rb` (`Toolkit`), `toolkit_binding.rb` (`ToolkitBinding`, the Engine's seam), `toolkit_command.rb` (`/toolkit`), `tools/registry.rb` (`Registry#toolkit`, `#left_out_names`), `web/public/toolkit_chip.js` | Which registered tools a session's prompts declare: saved in the session, resolved at a turn's start (`Engine#apply_toolkit!`), named in the prompt's not-loaded line, a kit's prompt text after the appended files; `chi.toolkit` and `ctx.use_toolkit` for plugins ([configuration.md](configuration.md#toolkits)). |
+| Toolkits | `toolkit.rb` (`Toolkit`), `toolkit_binding.rb` (`ToolkitBinding`, the Engine's seam), `toolkit_command.rb` (`/toolkit`), `tools/registry.rb` (`Registry#toolkit`), `tools/tool_surface.rb` (`ToolSurface#left_out`, read by the prompt and `/toolkit`), `web/public/toolkit_chip.js` | Which registered tools a session's prompts declare: saved in the session, resolved at a turn's start (`Engine#apply_toolkit!`), named in the prompt's not-loaded line, a kit's prompt text after the appended files; `chi.toolkit` and `ctx.use_toolkit` for plugins ([configuration.md](configuration.md#toolkits)). |
 | Tool index | `tools/tool_index.rb` (`Tools::ToolIndex`), `tools/deferred_tools.rb` | `find_tools` and `call_tool`: the tools a session knows but doesn't declare one by one (an mcp bundle's servers through `chi.tool_source`, the built-ins its toolkit leaves out), searched and called by name ([plugins.md](plugins.md)). On `api: anthropic` they also go out deferred, a hit loads its matches and the model calls them by name ([internals/anthropic.md](internals/anthropic.md)). |
 | Tool output cut | `tool_output_cut.rb` (`ToolOutputCut`), `tool_output_files.rb` (`ToolOutputFiles`) | A tool's output over `max_tool_output_chars` (a `memory_read`'s: `memory.read_max_chars`, 0 = none, plus a guard at half a known window), cut by the tool's policy; an execute's whole output saved in the session's `tool_output/` folder ([internals/tool-output-limits.md](internals/tool-output-limits.md)). |
 | Steer delivery | `steer.rb` (`Steer`), `delivery.rb` (`Delivery`), `steer_cut.rb` (`SteerCut`), `generation_phase.rb`, `waiting_steer.rb`, `steer_cut_after.rb` (`SteerCutAfter`), `cut_policy.rb` (`CutPolicy`) | A message for a running turn: at the next boundary, cutting a thinking-only generation, or queued for the turn's end ([internals/engine.md](internals/engine.md)). |

data/docs/bundles.md

@@ -1358,3 +1358,24 @@ bundles:
     timeout: 120       # seconds the side request may take (a number)
     max_tokens: 300    # the side answer's limit
 ```
+
+## The inline-widgets bundle
+
+`chi bundle install inline-widgets` (or the `dev` profile) installs the bundle shipped with chi. It is written only against
+this API (`lib/samagotchi/bundles/inline-widgets/plugin.rb`) and has no settings, commands or memories: it adds two
+[prompt sections](plugins.md#chiprompt_sectionname--ctx---and-chiprompt_changed) that tell the model chi web draws
+```` ```chi-ui ```` blocks ([the blocks](internals/inline-widgets.md)).
+
+- **picks**: when an answer leaves you two or more things to decide (review findings, a plan's open questions), a row
+  per item with its options as buttons, the recommended one picked to start with, a note per row, and **Fill reply**,
+  which puts your picks in the composer. Nothing is sent until you send it.
+- **walk**: a scenario you step through: who does what, what you see, what happens behind it, with a fork's cases to
+  choose from.
+- **Where it draws**: chi web, in the answers. The terminal shows the block's YAML, and a block chi can't read stays
+  YAML with a short note under it.
+- **Where the prompt has none**: a delegate child (its parent reads the report, nobody sees it drawn) and a one-shot
+  `chi -p … --non-interactive`. `/stats` lists the sections a session's prompt holds: `picks (inline-widgets), walk
+  (inline-widgets)`.
+- **Cost**: about 2,900 characters in the stable part of the prompt, the same at every build, so the prompt cache keeps.
+- **Uninstall**: `chi bundle uninstall inline-widgets` takes the sections out of new sessions' prompts (a session you
+  have open needs `chi sessions restart ID`); blocks already in a history still draw, since the drawing is chi web's own.

data/docs/cli.md

@@ -158,7 +158,7 @@ The loop for a bundle you're writing (the whole path: [bundle-authoring.md](bund
   bundle chi doesn't ship), `clash` (warn: a name chi ships, or one installed from elsewhere; the sandboxed install
   then forces), `install` (each Installer warning, a `needs` one as warn, and each plugin or hook load failure at
   the source `file:line`; skipped while a placeholder sha is unfilled), `registered` (info: each command, tool,
-  hook with its priority, init, toolkit, tool source and peer source), `hook-event` (warn: a `chi.on` event chi
+  hook with its priority, init, toolkit, tool source, peer source and prompt section), `hook-event` (warn: a `chi.on` event chi
   never fires), `settings` (warn: a `--set` the manifest's `settings:` rules out, as config.yml's `bundles:` is told), `api` (warn: a `ctx.*` / `chi.*` call or a keyword this chi's API lacks, read from the source with
   Prism against the API's own classes, on a path that never runs too; written on a local `ctx` / `chi` itself, so a
   `s = ctx.sessions` variable isn't followed; a name the plugin guards with `respond_to?` is left), `boundary` (warn: a `Samagotchi::` name outside "Stable for bundles"; a shipped bundle's listed

data/docs/guardrails.md

@@ -410,7 +410,7 @@ under the owner's guardrails, as the owner's own turns do: the rules, the
 protected paths and every approval the owner already granted apply, and an ask
 goes to the owner. It is a pair turn only when all three hold
 (`ParticipantMode.for_turn`, decided once at the turn's start:
-`GuardrailWiring#turn_mode`): the session has no `review:` key, its worker
+`GuardrailWiring#begin_turn`, into the turn's `TurnContext#participant_mode`): the session has no `review:` key, its worker
 names the `pair_turns` feature, and the participant's grant was issued with
 `mode: pair`, which chi share and the web's Invite stamp only when the warning
 they showed said their turns act. A grant from before, or one issued while an
@@ -690,7 +690,7 @@ runs with the owner's rules or System 1's auto-allows. The mode is decided once,
 at the start, from their grant's mode there (`ParticipantMode.live_for`) and
 saved on the child (`verify_fresh.mode`): `review` keeps every turn of it
 inside `ReviewBoundary` (read only), `pair` inside `PairBoundary`.
-`GuardrailWiring#turn_mode` reads the saved mode and never looks it up again,
+`GuardrailWiring#begin_turn` reads the saved mode and never looks it up again,
 and every turn of the child carries the participant as its author, whoever
 started it, so the boundary can't fall away for a turn the owner typed into it
 or for an author lookup that finds nobody (the child has no

data/docs/hooks.md

@@ -711,7 +711,7 @@ Notes:
 - Ordering: bundle hooks fire by `(priority, bundle_name, hook_name)` (lower priority first), then plain `config.yml` hooks in registration order.
 - Settings: a hook class with `initialize(settings = {})` gets the bundle's section of `config.yml` `bundles:` (see [Settings](#settings)).
 - A bundle can also ship a `plugin.rb` whose `chi.on(event)` blocks are bundle hooks too, next to commands and tools; see [Plugins](plugins.md). There `ctx.notify`, `ctx.steer` and the other `ctx` helpers act as this page's `event[:notify]`… do for the event the block runs for.
-- Shipped bundles (each but web-search in a profile: `core` or `dev`, see [Bundle profiles](memory.md#bundle-profiles-core-and-dev)): `chi bundle install guardrails` (rules, see [Guardrails](guardrails.md#the-guardrails-bundle)) and `chi bundle install known-names` (a hook, see [Guardrails](guardrails.md#the-known-names-bundle)), `chi bundle install source-links` (a hook: announces source refs, see [The source-links bundle](#the-source-links-bundle)), `chi bundle install btw` (a plugin: `/btw`, see [Bundles](bundles.md#the-btw-bundle)), `chi bundle install mcp` (a plugin: tools from MCP servers, see [Bundles](bundles.md#the-mcp-bundle)) `chi bundle install loop-guard` (a plugin: breaks tool-call loops, see [Bundles](bundles.md#the-loop-guard-bundle)), `chi bundle install check-in` (a plugin: checks on a long turn, see [Bundles](bundles.md#the-check-in-bundle)), `chi bundle install slow-commands` (a plugin: commands that ran past the execute limit are run as tasks next time, see [Bundles](bundles.md#the-slow-commands-bundle)), `chi bundle install agents-md` (a plugin: a nested AGENTS.md is steered into the conversation on the first touch under its directory, see [Bundles](bundles.md#the-agents-md-bundle)), `chi bundle install cost-cap` (a plugin: a per-session $ cap, `/cap`, see [Bundles](bundles.md#the-cost-cap-bundle)), `chi bundle install work-cap` (a plugin: a per-session cap on tool calls and active minutes, `/workcap`, see [Bundles](bundles.md#the-work-cap-bundle)), `chi bundle install ruby` (a plugin: an RSpec run with no examples at all, a hint, see [Bundles](bundles.md#the-ruby-bundle)) `chi bundle install skills` (a plugin: `/skill`, versions of skills, see [Bundles](bundles.md#the-skills-bundle)), `chi bundle install github-pr` (attached context: the branch's open PR, see [Bundles](bundles.md#the-github-pr-bundle)), `chi bundle install coordinator` (a plugin: parallel work in worktrees and child sessions, see [Bundles](bundles.md#the-coordinator-bundle)), `chi bundle install claude-peer` / `codex-peer` (a plugin: talk to a Claude Code or Codex session, see [Bundles](bundles.md#the-claude-peer-bundle)), `chi bundle install model-notes` (memories: reviewed model notes, see [Bundles](bundles.md#the-model-notes-bundle)) and `chi bundle install web-search` (a plugin: a `web_search` tool through your SearXNG, in no profile, see [Bundles](bundles.md#the-web-search-bundle)).
+- Shipped bundles (each but web-search in a profile: `core` or `dev`, see [Bundle profiles](memory.md#bundle-profiles-core-and-dev)): `chi bundle install guardrails` (rules, see [Guardrails](guardrails.md#the-guardrails-bundle)) and `chi bundle install known-names` (a hook, see [Guardrails](guardrails.md#the-known-names-bundle)), `chi bundle install source-links` (a hook: announces source refs, see [The source-links bundle](#the-source-links-bundle)), `chi bundle install btw` (a plugin: `/btw`, see [Bundles](bundles.md#the-btw-bundle)), `chi bundle install mcp` (a plugin: tools from MCP servers, see [Bundles](bundles.md#the-mcp-bundle)) `chi bundle install loop-guard` (a plugin: breaks tool-call loops, see [Bundles](bundles.md#the-loop-guard-bundle)), `chi bundle install check-in` (a plugin: checks on a long turn, see [Bundles](bundles.md#the-check-in-bundle)), `chi bundle install slow-commands` (a plugin: commands that ran past the execute limit are run as tasks next time, see [Bundles](bundles.md#the-slow-commands-bundle)), `chi bundle install agents-md` (a plugin: a nested AGENTS.md is steered into the conversation on the first touch under its directory, see [Bundles](bundles.md#the-agents-md-bundle)), `chi bundle install cost-cap` (a plugin: a per-session $ cap, `/cap`, see [Bundles](bundles.md#the-cost-cap-bundle)), `chi bundle install work-cap` (a plugin: a per-session cap on tool calls and active minutes, `/workcap`, see [Bundles](bundles.md#the-work-cap-bundle)), `chi bundle install ruby` (a plugin: an RSpec run with no examples at all, a hint, see [Bundles](bundles.md#the-ruby-bundle)) `chi bundle install skills` (a plugin: `/skill`, versions of skills, see [Bundles](bundles.md#the-skills-bundle)), `chi bundle install github-pr` (attached context: the branch's open PR, see [Bundles](bundles.md#the-github-pr-bundle)), `chi bundle install coordinator` (a plugin: parallel work in worktrees and child sessions, see [Bundles](bundles.md#the-coordinator-bundle)), `chi bundle install claude-peer` / `codex-peer` (a plugin: talk to a Claude Code or Codex session, see [Bundles](bundles.md#the-claude-peer-bundle)), `chi bundle install model-notes` (memories: reviewed model notes, see [Bundles](bundles.md#the-model-notes-bundle)), `chi bundle install decision-card` (a plugin: a long answer's question as a card, see [Bundles](bundles.md#the-decision-card-bundle)), `chi bundle install inline-widgets` (a plugin: prompt sections that teach the `chi-ui` blocks chi web draws, see [Bundles](bundles.md#the-inline-widgets-bundle)) and `chi bundle install web-search` (a plugin: a `web_search` tool through your SearXNG, in no profile, see [Bundles](bundles.md#the-web-search-bundle)).
 - Installing a bundle executes its hook code at `Engine` startup. Only install bundles you trust, as you would a gem. Hooks are **not** executed at install time (copy-only); they are `module_eval`'d at `Engine.new` inside per-bundle `Samagotchi::Bundles::<name>` namespaces (no top-level `require` collisions). Keep hook files side-effect-free at load time; do work in `#call` — top-level side effects (require, IO, `at_exit`, global assignment) run once per `Engine.new` (class redefinition is idempotent).
 
 Lifecycle:

data/docs/internals/anthropic.md

@@ -36,7 +36,7 @@ Paths are under `lib/samagotchi/llm/`.
 | `anthropic_wire.rb` | `AnthropicWire`: ChatLoop's wire messages as Messages' `system` and `messages`, the two breakpoints, tool ids and names |
 | `anthropic_assembly.rb` | `AnthropicAssembly`: a response from a whole body (`.from_message`) or stream events (`#add`), its usage in the OpenAI shape |
 | `dialect.rb` | `Dialect` (`STANDARD`, `FIREWORKS`): what a provider's `/v1/messages` does differently |
-| `../tools/deferred_tools.rb` | `Tools::DeferredTools.list`: the tools a request declares deferred (Deferred tools) |
+| `../tools/deferred_tools.rb` | `Tools::DeferredTools.list`: the tools a request declares deferred, from the turn's `ToolSurface` (Deferred tools) |
 | `prompt_cache.rb` | `PromptCache.control`: the `cache_control` a breakpoint carries (`cache.ttl`) |
 | `chat_loop.rb` | `ChatLoop#replay_blocks`, `#reasoning_history`'s floor, `Run#with_thinking` (saves `anthropic_content`), `#settle_dropped_thinking!` |
 
@@ -222,10 +222,10 @@ ones: the model sees their names only when something loads them, and the API acc
 `AnthropicMessages#loads_tools?(model)` says whether a request does this: the dialect's `tool_loading`, unless the
 host refused it for that model.
 
-`ChatLoop#tool_definitions(conversation, model:)` appends them (`Tools::DeferredTools.list`) only on such an
+`ChatLoop#tool_definitions(conversation, model:)` appends them (`ToolSurface#deferred_for`) only on such an
 adapter, and only with at least one tool declared (Messages wants one). The list, per request:
 
-1. the built-ins and plugin tools the toolkit reaches (`Registry#reachable_names`), in registry order;
+1. the built-ins and plugin tools the toolkit reaches (`ToolSurface#index_only`), in registry order;
 2. the tool index's source tools while `call_tool` is declared (`ToolIndex#deferrable`, via
    `Registry::Index#deferrable`): callable, the only tool with its acts_as, a name Messages takes, no registered
    tool's name; by acts_as (`mcp_<server>_<tool>`), sorted by name;
@@ -270,7 +270,7 @@ sets `:tool_changes` for the model: the retry and every later request drop the s
 
 A direct call of a deferred tool runs whether something loaded it or not (the API doesn't check): the Engine sets
 `TurnSettings#loads_tools` from the turn's final model (after the before_turn hooks), and then `ToolRunner#run` and
-`KernelLoop#dispatch` take a reachable built-in or plugin tool by its own name (`Registry#indexed`) through the normal gate, and wrap
+`KernelLoop#dispatch` take a reachable built-in or plugin tool by its own name (`ToolSurface#entry_for`) through the normal gate, and wrap
 an MCP tool's acts_as into the `call_tool` call it stands for (`ToolIndex#wrap`): `call_tool`'s row, rules and
 approvals. A reload rebuilds that wrapped call from the saved one (`BuiltinCalls.wrap_saved`). Each such call is
 logged (`tool_direct_deferred`, with `loaded:` whether the conversation had loaded it). On `api: openai` and the

data/docs/internals/attached-context.md

@@ -144,8 +144,10 @@ source's why. `task_p < TASK_MIN` (0.5) leaves the candidate unjudged; `due?` de
 lines (never twice at one owner-prompt count; one re-ask after `reask_after_turns`; then done). No answer writes
 nothing, so the next owner prompt asks again.
 
-The driver is the Engine, not the judge: `Engine#start_context_judge` (an owner turn's start; skipped for participants,
-review sessions and a Continue) and `judge_late_candidates` (a proposal after the prompts) call `context_judge_pass`.
+The driver is the turn stage `TurnStages::ContextJudge` (`turn_stages/context_judge.rb`), not the judge:
+`Engine#prepare_turn` calls its `start(turn)` after the toolkit suggestion settled and before `apply_toolkit!` (an owner
+turn's start; skipped for participants, review sessions and a Continue), and `Engine#judge_late_candidates` (a proposal
+after the prompts) forwards to its `late_candidates`; both make one pass (docs/internals/engine.md, "Turn stages").
 It first logs status changes (`ContextCandidatesLog.look`), returns at `mode: off`, builds the due `Job`s, and hands
 them to `SideJudgments` (`:context` kind: one thread, one batch per session at a time), asked at once on any host,
 the model's own server too.
@@ -153,10 +155,10 @@ the model's own server too.
 `ContextCandidateChoice.after_judged` acts on `fields["would"]` in `on` mode only: *attach* → `judge_attach` (a
 session source with `JUDGE_WHY`, no probability in the model-visible why), *offer* → one card (`offer_card`, buttons
 `/context attach NAME` and `/context decline NAME`, guarded by a `carded` log line). It re-checks that the candidate
-is still proposed, since the user may have chosen while it was asked. Cards are shown through the Engine's
-`context_choice` lambda, which holds them while a turn runs (`@context_cards_after_turn`). `choose` is the
-`/context attach|decline` command's body (`SessionCommands`), shared by the card's buttons; it refuses in a review
-session. An attach only writes the session folder: its note comes with the next between-turn delivery, never into a
+is still proposed, since the user may have chosen while it was asked. Cards are shown through the stage's choice
+lambda, which holds them while a turn runs; `run_turn`'s ensure shows them after `release_turn`
+(`show_cards_after_turn`). `choose` is the `/context attach|decline` command's body (`SessionCommands`), shared by the
+card's buttons; it refuses in a review session. An attach only writes the session folder: its note comes with the next between-turn delivery, never into a
 running turn.
 
 `ContextCandidatesLog` is `context_candidates.jsonl` beside the sessions folder (a `SideJudgments.log`: 0600, one

data/docs/internals/block-renderers.md

@@ -16,7 +16,14 @@ model. The TUI is untouched: it shows a fence as source.
    who draws what: `GET /api/block_renderers`, `:owner`. `GET /api/block_renderers/:bundle/:file` serves a file, `:owner`:
    the URL's names go through `BlockRenderers.script_path` (membership in a listed renderer's `load` before any path is
    made), then `Provenance.sha_matches?`; a changed file is 409 `renderer_changed`. ETag + `no-cache`, as static files.
-3. `block_host.js` (`createBlockHost`, wired in `app.js`; `participant.js` isn't): one `MutationObserver` per turn root,
+3. `block_watch.js` (`createBlockWatch`, made by `block_host.js`'s `createBlockHost`, wired in `app.js`; `participant.js`
+   isn't) finds and watches the blocks; `block_host.js` is its frame drawer (`createFrameDrawer`). The watcher asks an
+   ordered list of drawers, core ones first (`inline_widgets.js` for `chi-ui`: [inline-widgets.md](inline-widgets.md)), then the frame drawer, which waits for `/api/block_renderers`;
+   the first that `claims` the block's language draws it, and a language none claims is left alone. The contract
+   (`claims`, `needsDraw`, `draw`, its `reconsider`, `sessionChanged`) is in the module's header. The shared DOM
+   helpers live there too: `failBlock` and its `.block-note` (a click copies it), `holdingView`, `rejoin`, the
+   toggle's listener; frames, the cache, hang marks, size checks, the zoom and the theme redraw stay in
+   `block_host.js`. One `MutationObserver` per turn root,
    filtered to `TEXTS` (`text_roots.js`), so cards, the asking slot, question replies and delegate reports never draw, and
    every path that adds a block to a root is seen the same way. One `IntersectionObserver` per scroller, with an explicit `root`
    (with `root: null`, `rootMargin` doesn't pass an `overflow: auto` in between). Closed `<details>` fire on open. **A