samagotchi 0.154.0 → 0.155.0

data/docs/internals/engine.md

@@ -6,12 +6,17 @@ and the attached TUI, a `--non-interactive` one-shot) runs turns the same way wi
 they render.
 
 ```
-Engine#run_turn → backend.complete(...) → KernelLoop#run (native) or ChatLoop#complete (chat)
-  → per iteration: one generation, then ToolResponse.run_batch over the calls
-      → ToolRunner#run per call → Guardrails::Gate → KernelLoop#dispatch_tool_call
+Engine#run_turn → backend.complete(..., context:) → KernelLoop#run (native) or ChatLoop#complete (chat)
+  → per iteration: one generation, then ToolResponse.run_batch(context:) over the calls
+      → ToolRunner#run(call, context:) per call → Guardrails::Gate#evaluate(call, context:)
+        → KernelLoop#dispatch_tool_call(call, context) → the handler's ToolContext(kernel, context)
   → repeat until the model answers without tool calls, or the iteration limit
 ```
 
+`context` is the turn's `TurnContext` (`lib/samagotchi/turn_context.rb`, see "Turn and TurnContext" below): every
+step of the tool path takes it as an argument; none of them reads the turn from the kernel, the wiring or the
+Engine's ivars.
+
 ## Quick reference: the turn lifecycle
 
 ```
@@ -19,61 +24,63 @@ Engine#run_turn(session, prompt, on_event:, max_iterations:, cancel_controller:,
                 pending_input:, continue:, origin:, images:, id:, resumed:, resume_from:, input_waiting:)
   │
   ├── begin_turn(session, prompt, on_event:, cancel_controller:, origin:, continue:, id:, input_waiting:)
+  │     # a Verify turn's claim checked first: @verify_anchors.verified(session, anchor) (nil when its
+  │     #   quote isn't in the source session's answer)
   │     # (then, on a continue, turn.resumed = resumed (a step-limit Continue) and
   │     #  turn.resume_from = resume_from (its run's start; nil: it starts cold))
   │     # @session = session, session.status = RUNNING, used memories absorbed,
-  │     # TurnState#begin!(controller:, sink:, input_waiting:) (a new CancellationController when none
-  │     # is given; input_waiting: the caller's peek, Engine#input_waiting?, which task_wait,
-  │     # delegate_result's wait and execute's early hand-over poll),
-  │     # a recap in flight invalidated, GuardrailWiring#begin_turn(origin)
-  │     # Returns a Turn {session, prompt (nil on a continue), continue, on_event, controller,
-  │     #                 origin, started_at, id (the caller's id:, else a new uuid), resumed, resume_from,
-  │     #                 wall (MessageTime.now)}
+  │     # the TurnContext built whole first (new_turn_context: GuardrailWiring#begin_turn(origin, session:)
+  │     #   → TurnStart {git (a fresh GitInfo), participant (participants.json), mode}; id: the caller's
+  │     #   id:, else a new uuid; cwd, session_dir, state_dir; settings nil until generate),
+  │     # then TurnState#begin!(context:, controller:, sink:, input_waiting:): the context published with
+  │     # the running flag in one step (a new CancellationController when none is given; input_waiting:
+  │     # the caller's peek, Engine#input_waiting?, which task_wait, delegate_result's wait and execute's
+  │     # early hand-over poll), a recap in flight invalidated
+  │     # Returns a Turn {context, prompt (nil on a continue), continue, on_event, started_at, resumed,
+  │     #                 resume_from, wall (MessageTime.now)}; turn.id/session/origin/controller read
+  │     #                 the context
   │
   ├── Client.swap_probe_cancel(turn.controller)   # a Stop cuts this turn's /props probes
   │
-  ├── prepare_turn(turn, images)
-  │     # Emits :turn_started {session_id, prompt, turn_id, at (the turn's wall time, Turn#wall: read once,
-  │     #                      the user message's and the reminders' stamp too), continue: true (only on a continue),
-  │     #                      resumed: true (only on a step-limit Continue: resumed: given),
-  │     #                      images (only when there are any), cut_after (the model's cut wait, s)}
-  │     # start_toolkit_suggestion: ToolkitSuggest's ask on its own thread from a copied snapshot (audit and on
-  │     #   mode: one eligibility; SideJudgments' :toolkit kind: one in flight, warn-not-raise). Audit never blocks the turn or changes the session; on mode
-  │     #   returns a ToolkitSuggest::Pending the turn joins below. See configuration.md (Toolkits) and
-  │     #   guardrails.md (System 1).
-  │     # refresh_profile! (may ask the server's /props once)
-  │     # turn.settings = LLM::TurnSettings (vision, sampling, thinking; model_name, loads_tools … are set in
-  │     #   generate, after the hooks, from the final model),
-  │     #   from one EffectiveModel; ThinkingNotices#turn_started keeps the level and says one the host can't do
-  │     # announces guardrail load failures, starts and awaits plugin init tasks, applies staged tools,
-  │     #   then (on mode) settle_toolkit_suggestion: waits for the ask up to System 1's timeout from its
-  │     #   start, or a Stop (which wins over an answer already in, and cuts the ask's request through
-  │     #   Pending#cancel_controller; a Stop after a timeout doesn't), and on a candidate picked ≥ threshold
-  │     #   ToolkitBinding#suggest sets the session's toolkit, origin suggested, saved, with the notice;
-  │     #   then start_context_judge (owner turns only: ContextCandidatesLog#look, and unless
-  │     #   context.candidates.mode is off, ContextJudge's asks on SideJudgments' :context kind, each answer to
-  │     #   ContextCandidateChoice#after_judged (on mode: attach to the session's folder, or a card held while a
-  │     #   turn runs and shown from run_turn's ensure, show_context_cards_after_turn); on a shared
-  │     #   local System 1 host they wait for the turn's end: started before warm_up_next_turn, whose warm-up
-  │     #   waits for them, or from run_turn's ensure; docs/context.md, The judge);
-  │     #   then the session's toolkit (apply_toolkit!: Registry#toolkit, ToolIndex#refresh! for find_tools'
-  │     #   chi line, a prompt rebuild when it changed; a warn notice per plugin tool that arrived mid-session
-  │     #   with nothing to reach it, Registry#stranded_names). A Stop during the probes or the waits returns false
-  │     #   (the ask's line says canceled; an ensure marks one the turn never settled failed).
-  │     # fires the :session_start hook on the Engine's first turn, then the :before_turn hook
-  │     #   (a frozen copy of the history, the prompt, and resumed)
-  │     # turn_messages: system head + history + due reminders (:reminder_injected) + the user message
-  │     #   + the plugins' staged tool loads (ctx.load_tools: a kind "tool_change" system entry per bundle,
-  │     #   only when the turn's host takes tool changes; #append_tool_loads)
-  │     # Returns false when a Stop came during the probes, the init wait or the toolkit ask, else true
+  ├── prepare_turn(turn, images)                 # its skeleton; the stages are in "Turn stages" below
+  │     # emit :turn_started {session_id, prompt, turn_id, at (the turn's wall time, Turn#wall: read once,
+  │     #   the user message's and the reminders' stamp too), continue: true (only on a continue),
+  │     #   resumed: true (only on a step-limit Continue), images (only when there are any),
+  │     #   cut_after (the model's cut wait, s)}; an image error raised after it
+  │     @toolkit_suggestion.start(turn)          # before the probes: its latency hides behind them
+  │     refresh_profile!                         # may ask the server's /props once
+  │     turn.prepared_settings = turn_settings(session); refuse_images!
+  │     #   (LLM::TurnSettings: vision, sampling, thinking from one EffectiveModel; model_name, loads_tools …
+  │     #   come in generate, after the hooks; ThinkingNotices#turn_started says a level the host can't do)
+  │     STOP CHECK A → @toolkit_suggestion.abandon(turn, :canceled); return false
+  │     announce_guardrail_failures; start_init_tasks!; await_init_tasks; apply_staged_tools!
+  │     @toolkit_suggestion.settle(turn)         # on mode: the turn joins the ask, before anything is declared
+  │     @context_judge.start(turn)               # owner turns only; its asks run beside the turn
+  │     @objectives_stage.incoming(turn)         # System 1's objectives audit, owner and human prompts only
+  │     apply_toolkit!(session, on_event)        # Registry#toolkit, ToolIndex#refresh! for find_tools' chi
+  │     #   line, a prompt rebuild when it changed; a warn per plugin tool that arrived mid-session with
+  │     #   nothing to reach it (Registry#stranded_names)
+  │     refresh_participants!(session)
+  │     STOP CHECK B → return false              # before the hooks run or a reminder is used up
+  │     :session_start hook (the Engine's first turn), then :before_turn (a frozen copy of the history,
+  │     #   the prompt, resumed)
+  │     turn_messages(turn, image_refs)          # system head + history + due reminders (:reminder_injected)
+  │     #   + the user message + the plugins' staged tool loads (ctx.load_tools: a kind "tool_change" system
+  │     #   entry per bundle, only when the turn's host takes tool changes; #append_tool_loads)
+  │     ensure: @toolkit_suggestion.abandon(turn, :failed)   # nothing once the ask was settled;
+  │     #   then @toolkit_suggestion.finish(turn): the stage lets the turn and its Pending go
+  │     # Returns false at a STOP CHECK (stopped_before_model ends the turn canceled), else true
   │
   ├── generate(turn, max_iterations:, max_tool_output_chars:, pending_input:)
   │     # one EffectiveModel (after the hooks, which may switch the model): sync_kernel_client!, then
-  │     #   @kernel.turn_settings = turn.settings with model_name, window_setting, llm_context (the
-  │     #   session's, the model's/host's, else llm_context.strategy) and price
-  │     #   (hosts.<name>.models.<id>.price), all read per turn
+  │     #   turn.context = turn.context.with(settings: turn.prepared_settings with model_name,
+  │     #   window_setting, llm_context (the session's, the model's/host's, else llm_context.strategy),
+  │     #   price (hosts.<name>.models.<id>.price) and loads_tools, model_key/fallback_model_key (the
+  │     #   memory overlay keys) and model_name (the gate's rules' models:), all frozen now),
+  │     #   published by TurnState#replace_context
   │     # turn.limit = max_iterations or IterationLimit.for
-  │     # backend(model).complete(messages: turn.messages, ..., pending_input: turn_drain(pending_input))
+  │     # backend(model).complete(messages: turn.messages, ..., pending_input: turn_drain(pending_input),
+  │     #                         context: turn.context)
   │     # Returns LLM::ModelResult (text, conversation, canceled?, exhausted?, tool_activity,
   │     #                          context_status, empty_steps, empty_retries)
   │
@@ -85,9 +92,12 @@ Engine#run_turn(session, prompt, on_event:, max_iterations:, cancel_controller:,
   │     #   a continue turn's origin carries its offer turn's, ContinueOffer#run_continue_turn),
   │     #   and :turn_completed {result, turn_summary, display_pending} or :turn_canceled
   │     #   {cancellation_reason, cancelled_by, duration_ms} is emitted; before the replace,
-  │     #   stamp_opening puts a Verify turn's `verify` and a completed Revise turn's `revises`
-  │     #   (re-targeted to its stack's top) on the opening message, metadata never sent, and
-  │     #   every end event carries `turn_id`, :turn_completed `verify` / `verdict` / `revises` when there are
+  │     #   @verify_anchors.stamp_opening puts a Verify turn's `verify` and a completed Revise turn's
+  │     #   `revises` (re-targeted to its stack's top) on the opening message, metadata never sent,
+  │     #   @verify_anchors.record_verdict adds a completed Verify turn's verdict, the working set and
+  │     #   @objectives_stage.announce(session) go out in the same step, and every end event carries
+  │     #   `turn_id`, :turn_completed `verify` / `verdict` / `revises` when there are
+  │     # then @objectives_stage.outgoing(turn, result) (not for a canceled or exhausted turn)
   │     # then the :after_turn hook (status, messages, present: the AnswerDisplay presenter,
   │     #   refs: the AnswerRefs adder)
   │     # store_answer_display (one replace of the answer: `display` and/or `display_refs`;
@@ -95,18 +105,41 @@ Engine#run_turn(session, prompt, on_event:, max_iterations:, cancel_controller:,
   │     #   attached refs, or display: nil when the web was told to wait for it)
   │     # then the :session_end hook
   │
-  ├── warm_up_next_turn(turn, result)
+  ├── @turn_warmup.after(turn, result)
   │     # local llama.cpp on the native loop only: prefills the next turn's prompt while the user
   │     # reads (PromptWarmup; see prompt-caching.md, "The turn-end warm-up"). Never fails the turn.
   │
   └── ensure: release_turn(probe_cancel_before)
-        # TurnState#finish! (turn flag off, controller, sink and steers cleared)
+        # TurnState#finish! (turn flag off, controller, sink and steers cleared; the context kept as
+        #   the last one, Engine#last_turn_context, with the last settings when it never got its own)
         # SteerCut#finished! (its GenerationPhase finished, its WaitingSteer cleared)
         # probe cancel swapped back
         # the context window cache dropped, so the next turn asks the server again
         # steers left logged as dropped, activity recorded, turn-scoped hooks cleared
+        # then @context_judge.show_cards_after_turn (after the flag is released), then
+        # @objectives_stage.finally(turn): a completed turn's proposals shown, any other's dropped
 ```
 
+### Turn stages
+
+A step that keeps state across the turn (its preparation, its end) is a collaborator under `lib/samagotchi/turn_stages/`, built
+in `Engine#initialize` (before the plugins load) from constructor arguments, never reading the Engine's ivars, and
+called by name from the skeleton above, next to the STOP CHECKs. Their input is the `Turn` (and its `TurnContext`);
+their state is their own. The Engine's public methods forward to them (`warm_toolkit_suggestion!`,
+`announce_objectives`, `propose_objective`, the private `judge_late_candidates`).
+
+| Stage | Built with | Called | State |
+|---|---|---|---|
+| `TurnStages::ToolkitSuggestion` (ToolkitSuggest's ask: audit and on mode, one eligibility, a copied snapshot, SideJudgments' `:toolkit` kind) | `side_judgments`, `host_registry`, `toolkit_binding`, `tools`, `state_dir`, `recording`, `runs` | `start(turn)` before `refresh_profile!`; `settle(turn)` after `apply_staged_tools!` (on mode: waits up to System 1's timeout from its start, or a Stop, which wins over an answer already in and cuts the ask through `Pending#cancel_controller`; a pick ≥ threshold → `ToolkitBinding#suggest`); `abandon(turn, why)` at STOP CHECK A (`:canceled`) and in the ensure (`:failed`), then `finish(turn)` there; `warm!(session)` / `stop_warmup` (Worker start, `shutdown`) | the turn's `ToolkitSuggest::Pending` while it prepares (turn thread only; another turn's is never touched; dropped at `finish`), the warm-up thread |
+| `TurnStages::ContextJudge` (the attached-context candidate judge: [attached-context.md](attached-context.md), [context.md](../context.md) "The judge") | `side_judgments`, `host_registry`, `state_dir`, `recording`, `session`, `messages`, `turn_running`, `show_card` | `start(turn)` after `settle`, before `apply_toolkit!` (owner turns only: `ContextCandidatesLog#look`, then unless `context.candidates.mode` is off the due asks on SideJudgments' `:context` kind); `late_candidates` (a plugin's late proposal); `show_cards_after_turn` from `run_turn`'s ensure, after `release_turn` | the cards an answer brought while a turn ran, under their mutex |
+| `TurnStages::Objectives` (System 1's objectives audit, ObjectivesAudit; the view; the model's proposals: [objectives.md](objectives.md)) | `side_judgments`, `host_registry`, `state_dir`, `recording`, `runs`, `synchronize`, `announce`, `running`, `show_card` | `incoming(turn)` after the judge's `start`; `announce(session)` inside `end_turn`'s event step (and `Engine#announce_objectives` between turns); `outgoing(turn, result)` in `complete_turn`, after the end event and before `:after_turn`; `note(session, note)` (`add_context_note`); `propose(proposal)` (`Engine#propose_objective`); `finally(turn)` in `run_turn`'s ensure, after the judge's cards | the turn's proposals under their mutex (drained at `finally`), the last view announced, the audit |
+| `TurnStages::Warmup` (the turn-end warm-up, PromptWarmup: [prompt-caching.md](prompt-caching.md), "The turn-end warm-up") | `prompt_warmup`, `kernel`, `turn_state`, `model_settings`, `model`, `system_prompt`, `reminders_due`, `next_turn_waiting` | `after(turn, result)` after `complete_turn` (reads `turn.context.settings`) | none (the PromptWarmup keeps its pin and thread) |
+| `TurnStages::VerifyAnchors` (Verify and Revise anchors) | `state_dir` | `verified(session, anchor)` in `begin_turn`; `stamp_opening(messages, turn, outcome)` and `record_verdict(turn, outcome)` inside `end_turn`'s event step | none |
+
+On a shared local System 1 host the judge's asks wait for the turn's end: started before `TurnStages::Warmup#after`, whose
+warm-up waits for them, or from `run_turn`'s ensure (docs/context.md, The judge). See configuration.md (Toolkits) and
+guardrails.md (System 1) for the suggestion.
+
 ### Error paths
 
 ```
@@ -176,7 +209,7 @@ Stopped before the model was asked (prepare_turn returned false):
 **Degrading.** Work that has a fallback when it fails (a prompt section left out, an empty list from the Bridge) runs
 in `Degrade.call(area, event, fallback:, rescue:) { … }` (`degrade.rb`): same rescue class and fallback as a bare rescue,
 plus one WARN in the debug log per process for each `[area, event]` (DEBUG after; nothing on stderr). A bare `rescue`
-whose body is only a literal (`nil`, `false`, `[]`, `{}`, `""`, `0`) is flagged in lib by the `Samagotchi/SilentRescue`
+whose body is only a literal (`nil`, `false`, `[]`, `{}`, `""`, `0`, or an array of only those: `[nil, nil]`) is flagged in lib by the `Samagotchi/SilentRescue`
 cop; a silence that is right (a client gone, a routine probe, Log's own internals) carries `# degrade-ok: why`.
 
 ## The model↔tool loop
@@ -252,9 +285,10 @@ ChatLoop#complete(messages:, max_iterations:, on_stream_event:, cancel_controlle
 
 The differences from the native loop:
 
-- The tools go in each request's `tools` field (`tool_definitions(conversation, model:)`), not in the system prompt.
+- The tools go in each request's `tools` field (`tool_definitions(conversation, model:)`, the turn's
+  `ToolSurface#schemas`), not in the system prompt.
   On an adapter that loads tools (`#loads_tools?`: `AnthropicMessages`), the tools the session reaches but doesn't
-  declare follow, `defer_loading: true` (`Tools::DeferredTools`; anthropic.md, "Deferred tools"); the Run keeps the
+  declare follow, `defer_loading: true` (`ToolSurface#deferred_for`; anthropic.md, "Deferred tools"); the Run keeps the
   last request's deferred names and logs a call of one (`tool_direct_deferred`).
 - The conversation is converted to the OpenAI wire format (`wire_messages`), for every chat host;
   `AnthropicMessages` translates that again into Messages' `system` and content blocks (`LLM::AnthropicWire`).
@@ -298,25 +332,26 @@ Both loops run a batch of calls the same way:
 ```
 One iteration with tool calls:
   KernelLoop#dispatch_calls / ChatLoop::Run#dispatch
-    → ToolResponse.run_batch(runner, calls, iteration:, emit:, on_stream_event:, cap:)
-       # chat passes a block, called with each run as it finishes
+    → ToolResponse.run_batch(runner, calls, context:, iteration:, emit:, on_stream_event:, cap:)
+       # context: the turn's TurnContext (the native run's, ChatLoop::Run's); chat passes a block,
+       # called with each run as it finishes
       → :tool_dispatch_started {iteration, call_count}
-      → for each call: ToolRunner#run(call, iteration:, call_index:, call_count:,
+      → for each call: ToolRunner#run(call, context:, iteration:, call_index:, call_count:,
                                       on_stream_event:, max_tool_output_chars:)
           → under TurnSettings#loads_tools, a direct call of a source tool's acts_as (mcp_fs_read) is wrapped
             into the call_tool call it stands for (Registry::Index#wrap, ToolIndex#wrap)
           → first, the call's entry unwraps it (Registry::Entry#unwrap: a call_tool of chi/<name>, a built-in or
             a plugin tool, becomes that tool's call with via: "call_tool", ToolIndex#unwrap); the rest sees the
             real call
-          → a tool the session's toolkit leaves out (Registry#left_out; with via:, one Registry#indexed doesn't
-            reach) skips the gate: no hooks, no card; KernelLoop#dispatch answers it (the call_tool route for a
-            reachable tool, the not-loaded error for a removed one). Under TurnSettings#loads_tools a reachable
+          → a tool the session's toolkit leaves out (ToolSurface#left_out; with via:, one the surface's index_only
+            doesn't hold) skips the gate: no hooks, no card; KernelLoop#dispatch answers it (the call_tool route for a
+            reachable tool, the not-loaded error for a removed one). Under the surface's loads_tools a reachable
             built-in or plugin tool called by its own name is no such call: it runs through the gate, and KernelLoop#dispatch
-            takes it (#loaded_entry)
-          → Guardrails::Gate#evaluate (the before_tool_call hooks, then the core checks)
+            takes it (ToolSurface#entry_for)
+          → Guardrails::Gate#evaluate(call, context:) (the before_tool_call hooks, then the core checks)
           → :tool_call_started
-          → an ask verdict: Gate#settle_ask (asks the user, records waited_ms)
-          → KernelLoop#dispatch_tool_call, or the denial text
+          → an ask verdict: Gate#settle_ask(verdict, context:) (asks the user, records waited_ms)
+          → KernelLoop#dispatch_tool_call(call, context), or the denial text
           → :tool_call_completed, then the :after_tool_call hook
           → returns a ToolRun value object with output, capped_output, truncated, activity, images, shown_params,
             shown_label, refs, diff and output_file; fields a call doesn't produce are nil
@@ -328,7 +363,9 @@ One iteration with tool calls:
       (one per call of the batch for native, one for chat); LLM context edits name outputs by them
 ```
 
-**ToolRunner** (`ToolRunner#run`):
+**ToolRunner** (`ToolRunner#run`): what it reads of the turn is the `context:` it is given (a `TurnContext`): the
+session's folders (`cwd`, `session_dir`), the settings' vision, LLM context layers and `loads_tools`, the
+participant's author and mode; the kernel gives it only what lives as long as the Engine (tools, hooks, the gate).
 - Unwraps a call_tool of a built-in first (`Registry::Entry#unwrap`), so `original`, the params and the label
   are the built-in's and no "ran as:" line follows.
 - Runs the gate first, so `:tool_call_started` shows the call that will run (a before_tool_call hook may
@@ -344,15 +381,16 @@ One iteration with tool calls:
   `refs` is a plugin tool's row refs: its registry entry's `refs` (chi.tool's `refs:` lambda, `ToolSpec#per_call`), run
   once per call by `RowRefs.for` (never raises: a raise or a non-list gives none, `tool_refs_failed`; each entry a
   `Ref`, a bad one dropped, `tool_refs_rejected`; a relative file resolved against the session's folder
-  (`KernelLoop#session_cwd`, else the process's), one outside it (its spelling or its real path) dropped, a kept one
+  (`TurnContext#cwd`, else the process's), one outside it (its spelling or its real path) dropped, a kept one
   stored under the real path; at most `RowRefs::MAX_REFS` and `MAX_BYTES`). `ToolRowFields.for` can't build it (no plugins on a reload), so the run carries it
   as `refs:`, saved with the result as `tool_refs` (`ToolResponse::SAVED_KEYS`, never sent), and
   `MessageParts#tool_part` reads it back through `RowRefs.for_display` (checked again). The page binds them to the
   row's title (`refs.js bindRowRefs`, from `turn_block.js` live and on a reload): the first ref on it, the rest in its
   menu.
 - Settles an ask verdict after `:tool_call_started`, so a UI shows the tool line and then the approval.
-- Dispatches through `KernelLoop#dispatch_tool_call`, or writes the denial text. Unknown tools are answered in
-  `KernelLoop#dispatch` ("Error: no such tool ...", never repeating the wrong name).
+- Dispatches through `KernelLoop#dispatch_tool_call`, or writes the denial text. `KernelLoop#dispatch` runs the call
+  on the entry `ToolSurface#entry_for` gives; one without an entry gets `ToolSurface#unknown_tool_error` ("Error: no
+  such tool ...", never repeating the wrong name).
 - For edit and write: diffs the file before and after, and refreshes a memory's index line
   (`MemoryBundle::IndexSync`).
 - Attaches returned images, at most `MAX_IMAGES_PER_RESULT` (4) per result.
@@ -360,7 +398,7 @@ One iteration with tool calls:
   policy: `read` and most tools are cut to their head and end with `[cut: N of M chars; read it in parts]` (N
   kept of M, the whole within the cap unless the cap is shorter than that line); an `execute` result keeps a head
   and a long tail with a gap line between them, its whole output saved in `sessions/<id>/tool_output/`
-  (`ToolOutputFiles`, through `KernelLoop#session_dir`, which the Engine sets). See
+  (`ToolOutputFiles`, in the turn's `TurnContext#session_dir`). See
   [Tool output guardrails](tool-output-limits.md#the-runners-cut-max_tool_output_chars). The model (both loops), the
   event and the after_tool_call hook get that text.
 - Emits `:tool_call_completed` {iteration, call_count, call_index, tool, output, output_truncated, output_file,
@@ -384,6 +422,31 @@ One iteration with tool calls:
 A denied call gets denial text in place of its output; the rest of the batch still runs. After a hook's
 `stop_turn`, the gate denies every remaining call of the batch.
 
+**ToolSurface** (`lib/samagotchi/tools/tool_surface.rb`, `Tools::ToolSurface`): the turn's tools as one frozen
+value, built once in `Engine#generate` (`ToolSurface.for(registry, layers:, loads_tools:)`, the settings' LLM context
+layers and the host's `loads_tools` known there) into `TurnContext#surface`. The Registry is its only input (its
+lists `entries`, `reachable_names`, `left_out_names`, `removed_names`, `stranded_names`, read under the Registry's
+toolkit or a `toolkit:` given). It holds `declared` (the entries the request declares, in prompt order), `index_only`
+(left out, reached by `call_tool`), `left_out` (`{name => :indexed | :user_only}`), `removed`, `stranded`,
+`registered`, `toolkit`, `reaching_kit`, `index`, `layers` and `loads_tools`, and answers `entry_for(call)` (a `via:` call only from `index_only`; a direct one from
+`declared`, or `index_only` under `loads_tools`), `unknown_tool_error(name, via:)`, `schemas` and
+`deferred_for(conversation)` (`Tools::DeferredTools.list` over the surface; the index's source tools are asked per
+request, so a late MCP server joins mid-turn as before). Its readers: `KernelLoop#dispatch`,
+`ChatLoop#tool_definitions` / `#deferred_tools` (whether to append the deferred ones is still the adapter's
+`#loads_tools?`, asked per request: a refusal turns it off mid-turn), `ToolRunner`'s unwrap, wrap, left-out and
+group-refusal checks, and the tool index: `find_tools`' and `call_tool`'s handlers take the surface from their
+`KernelLoop::ToolContext#surface`, and the call tool's unwrap and the index's `deferrable` / `wrap` / `unreached`
+are given the runner's or the deferred list's (its `chi` group is the surface's `index_only`). A change while the turn
+runs (`/toolkit`, a staged `chi.replace_tools`, a direct `Registry#register`) shapes the next turn's declared,
+searched and dispatched tools only. A context without one (a bare kernel or loop, a spec) computes one on read
+(`ToolSurface.of(context, registry)`); nothing caches or invalidates it.
+
+Readers outside a turn compute one on read (`ToolSurface.for`). On the turn thread, from the Registry: the system
+prompt, once per build before `generate` knows `loads_tools` (`SystemPrompt::Built#surface`; engine_tool_surface_spec
+checks it), `#warn_stranded`, the toolkit suggestion's logged lists (under full), the tool index's `#declare`,
+`#refresh!`, `call_targets` and `call_preview`. Off it, from `ToolkitBinding#published` (below): `#explained`
+(`/toolkit`, the snapshot, the plugin host's `declared_tools`) and `ctx.load_tools`' `#deferred_name`.
+
 ## State management
 
 ### TurnState (cross-thread)
@@ -394,6 +457,8 @@ read: the idle scheduler, the Bridge's request threads, plugin threads, the UIs.
 ```
 TurnState
   ├── running?
+  ├── context           (the running turn's TurnContext; nil between turns)
+  ├── last_context      (the last finished turn's, kept while the next one runs)
   ├── controller        (the running turn's CancellationController)
   ├── thread, ended     (the turn's own thread; its end event is out: post-turn work)
   ├── sink              (the turn's on_event)
@@ -402,20 +467,38 @@ TurnState
   └── activity clock    (last_activity_at, activity_seq)
 ```
 
-- `begin!(controller:, sink:)`: running, with controller and sink (and the calling thread, the turn's own), in one
-  step; carried steers become steers.
+- `begin!(context:, controller:, sink:)`: running, with the turn's context, controller and sink (and the calling
+  thread, the turn's own), in one step; carried steers become steers. `Engine#begin_turn` builds the context whole
+  before it (GuardrailWiring#begin_turn's mode and git included), so no reader sees a running turn with the last
+  turn's author.
+- `replace_context(context)`: the turn thread's new context for its running turn (`generate`'s settings), one
+  assignment of a frozen value; refused from another thread or for another turn's id.
 - `ended!`: the turn's end is decided (`end_turn`, next to `turn.ended`): its after_turn / session_end hooks run
   after it and before `finish!`.
 - `own_controller(handler:)`: the controller for work done for the turn itself, which a plugin's `ctx.http` call
   without `cancel:` stops with (`Plugin::Host#cancel_controller`, `Engine#plugin_cancel_controller`): the turn's, on
   its thread or inside a plugin handler, until `ended!`; nil elsewhere (an anytime command, a service, a plugin's
   own thread) and outside a turn. An init task's own controller wins inside one.
-- `finish!`: not running, controller, thread and sink cleared; returns the steers never taken (logged as dropped).
+- `finish!`: not running, context, controller, thread and sink cleared, the context kept as `last_context` (with the
+  last settings when the turn never reached `generate`); returns the steers never taken (logged as dropped).
 - `steer(text, source:)`: queues a steer for the running turn (false with no turn).
 - `steer_next_turn(text, source:)`: queues a steer for the next turn that begins.
 
 The lock is a leaf: nothing is called out while it is held.
 
+**Reading the turn from another thread.** A thread off the turn (a Bridge request, an anytime command, a plugin's
+thread, a hook fired by one) reads the running turn only through `Engine#turn_context` (`TurnState#context`, nil
+between turns) and `Engine#last_turn_context`, one read each, never through the kernel, `GuardrailWiring` or an
+Engine ivar. The readers that do: `Engine#turn_author` (`ctx.turn_author`, the hooks' `author:`, the judgments'
+`participant:`, `ObjectivesCheck`), `#side_author` (the recap's: the last turn's), `EventFanout#working_set_llm_context`
+(`/working-set`'s list: the running turn's settings, the last turn's until it has its own) and
+`#live_conversation` (nil unless the loop's `LLMContextForget::Turn#turn_id` is the running turn's). The turn's own
+code takes the context as an argument (the tool path, `guard_participant_spend`, `TurnStages::Warmup#after`'s
+`turn.context.settings`); cancel stays `TurnState#controller` (a Stop never reads `context.controller` off the
+turn). `spec/turn_context_readers_spec.rb` reads each from a thread the moment a turn is published. The tool
+Registry likewise: off the turn thread it is `ToolkitBinding#published`, a frozen `Registry#snapshot` (its entry set;
+the `Entry` Structs shared) swapped at the Engine's build, after `apply_staged_tools!` and after `apply_toolkit!`.
+
 ### EffectiveModel (a snapshot per read)
 
 `EffectiveModel.of(registry, choice)` resolves the model once (`HostRegistry#resolve`: host, client, the id
@@ -464,19 +547,47 @@ host can't do, off the model didn't honour, a host refusing the thinking fields
 keeps the turn's `[level, ModelTarget]` and whether the generation thought; `turn_settings` and the stream handler
 call it. Turn thread only.
 
-### Turn (Engine::Turn)
+### Turn and TurnContext
 
-The turn as the Engine sees it (the KernelLoop has its own `Turn` struct):
+One source of truth: the `TurnContext` holds what the tool path reads of a turn, and `Engine::Turn` keeps only
+its lifecycle state, reading the rest from its context (`turn.id`, `turn.session`, `turn.origin`,
+`turn.controller` are the context's). The KernelLoop has its own `Turn` struct, a run's.
 
 ```ruby
-Turn = Struct.new(:session, :prompt, :continue, :on_event, :controller, :origin, :started_at, :messages, :ended,
-                  :settings, :id, :limit, :resumed, :resume_from) do
+TurnContext = Data.define(:id, :session, :origin, :author, :participant_mode, :participant, :controller, :cwd,
+                          :session_dir, :state_dir, :git, :settings, :model_key, :fallback_model_key, :model_name,
+                          :surface)   # frozen; TurnContext.none for a bare kernel, a spec, the bundle test kit
+Turn = Struct.new(:context, :prompt, :continue, :on_event, :started_at, :messages, :ended, :prepared_settings,
+                  :limit, :resumed, :resume_from, :wall, :verify, :revises, :outcome) do
   def resumed? = resumed ? true : false                           # a step-limit Continue
-  def tag(event) = origin ? event.merge(origin: origin.to_h) : event   # boundary events carry the origin's wire Hash
+  def tag(event) = origin.empty? ? event : event.merge(origin: origin.to_h)   # boundary events carry the origin
   def elapsed = ...                                               # seconds since started_at
 end
 ```
 
+- `TurnContext` is built in `begin_turn` (`new_turn_context`) and published by `TurnState#begin!`; `settings` (the
+  `LLM::TurnSettings` the requests send), `model_key`/`fallback_model_key` (memory overlays) and `model_name` (the
+  gate's rules' `models:`) are nil until `generate` sets them, after the `before_turn` hook that may switch the
+  model (`turn.prepared_settings`, computed before the hooks, give vision, sampling and thinking: a hook's switch
+  gets the old model's, as before). `surface` (the turn's `Tools::ToolSurface`, see "Shared: ToolResponse (per
+  batch) and ToolRunner (per call)") is nil until `generate` builds it with the settings.
+- The live bits are objects it holds, not copies: `session` (its working-set pins are read at call time),
+  `controller` (cancel state), `git` (`Guardrails::GitInfo`, the per-turn git cache).
+- Down the tool path it is an argument: `ModelBackend#complete(context:)` → `KernelLoop#run(context:)` (the run's
+  own copy takes the run's model name; `KernelLoop#context` / `#turn_settings` read it on the turn thread, the last
+  run's after it) or `ChatLoop#complete(context:)` (`ChatLoop#turn_context`, its Run's) → `ToolResponse.run_batch` →
+  `ToolRunner#run` → `Guardrails::Gate#evaluate` / `#settle_ask` and `KernelLoop#dispatch_tool_call(call, context)` →
+  the handler's `KernelLoop::ToolContext.new(kernel, context)` (`participant_mode`, `model_key`, `muted_memory_read`,
+  `forget_outputs`). The generation guard gets it too (`KernelLoop::Services#generation_guard`, `guard_participant_spend`).
+- After a chat-loop turn the kernel's own `context` / `turn_settings` still hold the last native run's (a chat run
+  never sets them), and `ChatLoop#turn_context` keeps its last run's: both are the turn thread's working copies, so
+  a reader outside the turn uses `Engine#turn_context` / `#last_turn_context` instead.
+- A spec runs a loop, a runner or a gate outside an Engine turn with `run_context(settings: …)` (spec/support/test_kernel.rb).
+- What lasts the Engine's life is not in it: `KernelLoop::Services` (hooks, tools, reminder store, mutes, the
+  question handler, peers, the gate, warm-up, the generation guard), one frozen value the kernel gets at
+  `KernelLoop.new(services:)` or `#attach` (a spec's kernel: `attach_services(kernel, tools: …)`). No turn field
+  goes in Services, no Engine-lifetime one in TurnContext.
+
 - `messages` is what the Engine sends: system head, history, reminders, the prompt. The loop works on its own
   copy; the Engine keeps `result.conversation` after a normal end or a Stop, and the error's partial
   conversation after a failure.
@@ -485,9 +596,10 @@ end
 - `on_event` is the turn's sink.
 - `ended` is set by `end_turn`.
 - The live conversation: both loops register the array they append to on the kernel
-  (`KernelLoop#llm_context_turn`, `LLMContextForget::Turn#conversation`; `KernelLoop#start_turn`,
-  `ChatLoop::Run#initialize`). `Engine#live_conversation` returns it while a turn runs (nil otherwise: the kernel
-  never clears it). A worker's drain (`Worker#pending_input_drain`, on the turn's thread at every iteration
+  (`KernelLoop#llm_context_turn`, `LLMContextForget::Turn#conversation`, tagged with the run's `turn_id`;
+  `KernelLoop#start_turn`, `ChatLoop::Run#initialize`). `Engine#live_conversation` returns it while a turn runs and
+  only once its loop registered it (nil otherwise: the kernel never clears it, and the turn id tells the last turn's
+  from this one's). A worker's drain (`Worker#pending_input_drain`, on the turn's thread at every iteration
   boundary) copies it, with the lines that boundary merges, into `Session#turn_checkpoint` (`TurnCheckpoint`):
   every save while the turn runs writes that copy with an `interrupted_turn` mark instead of the session's
   messages, written at the first boundary and then at most every 10 s, so a killed worker loses at most that much
@@ -581,9 +693,10 @@ make theirs, and `Engine#run_turn`, the Worker and `GuardrailWiring` pass it on.
 `TurnOrigin#participant_author` does. The boundary events (`:turn_started`, `:turn_completed`, `:turn_canceled`, `:turn_failed`) also carry
 `origin` when the turn was queued with one: `{client_id:, enqueued_id:}`, plus `author:` when someone other than
 the session's owner wrote it (its input file's `author`, stamped by chi web from the request's `Web::Principal`).
-An owner's turn has no `author` anywhere: not in its input file, its origin or the session. `GuardrailWiring#begin_turn`
-gets the origin, and `#turn_author` reads its participant author for the gate's checks; the guardrails `Context`
-(the hooks' `context`) keeps the wire Hash.
+An owner's turn has no `author` anywhere: not in its input file, its origin or the session. The turn's
+`TurnContext` carries the origin and its participant author (`TurnContext#author`) for the gate's checks
+(`GuardrailWiring#begin_turn` decides the participant's mode from it); the guardrails `Context` (the hooks'
+`context`) keeps the wire Hash.
 
 Where a participant's author (`"p:<id>"`; `Steer.participant_author?`: any author but none or `"owner"`) goes:
 
@@ -606,13 +719,14 @@ Where a participant's author (`"p:<id>"`; `Steer.participant_author?`: any autho
   `Worker#run_prompt` checks their link and cap (`participant_refusal`: `participants.json`'s entry and cap against
   `SessionMetrics#spend`) before their turn starts and after it ends (the owner's notice, once per cap). A Continue
   keeps the offer turn's author (`ContinueOffer#run_continue_turn`, from `last_turn.author`).
-- **The gate**: `GuardrailWiring#participant_boundary` is the core check after the load failures, picked by
-  `#turn_mode`: `Guardrails::PairBoundary` for a pair turn, `Guardrails::ReviewBoundary` for a review one. Both read
-  `#turn_author` and are no-ops for the owner's turns; the review boundary denies a participant's turn everything
+- **The gate**: `GuardrailWiring#participant_boundary(turn)` is the core check after the load failures, picked by
+  the call's `TurnContext#participant_mode`: `Guardrails::PairBoundary` for a pair turn, `Guardrails::ReviewBoundary`
+  for a review one. Both read the turn's `author` and are no-ops for the owner's turns; the review boundary denies a participant's turn everything
   outside `Toolkit::REVIEW_TOOLS` (not `forget_outputs`), the pair boundary denies secrets, owner-voiced tools and
   `ask_user_question` and always asks before a write that may land outside the project (docs/guardrails.md).
   The declared tools stay the session's (D3: no rebuild per author).
-- **Hooks and plugins**: `Engine#turn_author` (the running turn's participant author, nil otherwise) is the hook
+- **Hooks and plugins**: `Engine#turn_author` (the running turn's participant author, nil otherwise: the
+  published `TurnContext#author`, so any thread reads the running turn's from its first moment) is the hook
   runtime's `turn_author` (`Hooks::Registry#with_runtime` adds `author:` to every event of such a turn) and the
   plugin host's (`ctx.turn_author`).
 - **Spend**: the analytics turn record's `author` feeds `SessionMetrics#spend` / `spend_by_author` (the snapshot's
@@ -655,11 +769,14 @@ Engine initialization (in this order, among other things):
     declared per toolkit by Registry#declared? (a source registered at load, or a tool registered then that
     the toolkit leaves reachable: Registry::Index#loaded; Toolkit::Resolved#declares? treats built-ins and
     plugin tools alike: full declares both, another kit its list and adds) and
-    sets call_tool's unwrap (Tools::ToolIndex: the chi group from Registry#reachable_names, the sources'
+    sets call_tool's unwrap (Tools::ToolIndex: the chi group from ToolSurface#index_only, the sources'
     groups, search, call checks, the unwrap; a source runs the call with its own plugin Context)
   @reminder_store = ReminderStore.new (the kernel gets it), @reminder_queue, @reminders
-  wire_kernel: @kernel = KernelLoop.new(client:, profile:, hooks:, reminder_store:, tools:)
-  @kernel.guardrail_gate = @guardrail_wiring.gate; @kernel.warmup = PromptWarmup.new
+  wire_kernel: one KernelLoop::Services (Engine-lifetime, never per turn: hooks, tools, reminder_store,
+    muted_memory_names, question_handler, peers (PeerView), gate (@guardrail_wiring.gate(hooks:, tools:): values,
+    both built by now), warmup (PromptWarmup), generation_guard) →
+    @kernel = KernelLoop.new(client:, profile:, model_name:, services:), or a given kernel's #attach(services);
+    then sync_kernel_client! (the client is no service: a model switch swaps it, KernelLoop#client=)
   @hooks.runtime = @hook_routes.runtime (HookRoutes, built first: what a hook or plugin does reaches the UIs)
   @native_backend = LLM::NativeBackend.new(kernel: @kernel)
   @prompt_builder = SystemPrompt.new(...)
@@ -672,7 +789,8 @@ Model switching, Engine#switch_model!(model_name, persist_default:, typed:):
     one assignment)
   → drops the given profile and the profile resolution (resolved again on first need; one that another
     thread finishes for the old model is neither kept nor applied: #store_profile)
-  → sync_model_key!, @prompt_builder.reset! (the system prompt is built again)
+  → sync_model_key! (the next turn's TurnContext takes the keys), @prompt_builder.reset! (the system prompt is
+    built again)
   → sync_kernel_client! (the kernel talks to the new host), the context window cache dropped
   → the old model's ctx dropped: @metrics.forget_model_reports! (its window and profile reports) and
     @last_context_status = nil; /model (SessionCommands#switch_model) then calls #announce_switched_context!
@@ -729,7 +847,7 @@ loops). It is display-only and never reaches the wire (prompt-caching.md, rule 7
 `MessageTime.gap_line` (10 min, `GAP_SECONDS`).
 
 `: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
+model's opens, never from `QuestionDesk`: `Engine#request_question` (the kernel's `Services#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 (`Engine::RelayPeer#open_question` → `Engine#open_question`) and `post` (the step-limit question) never
@@ -766,7 +884,9 @@ step's text ([architecture.md](../architecture.md), the `display_refs` paragraph
 
 ## Guardrails
 
-`ToolRunner` asks the kernel's `Guardrails::Gate` (set by the Engine from `GuardrailWiring`) before each call;
+`ToolRunner` asks the kernel's `Guardrails::Gate` (set by the Engine from `GuardrailWiring`) before each call,
+with the call's `TurnContext` (`Gate#evaluate(call, context:)`: its controller, model key and name, and what
+`GuardrailWiring#context(turn)` / `#checks(turn)` make of it; `GuardrailWiring` keeps no per-turn state);
 the gate is not itself a hook. `Gate#evaluate` fires the `:before_tool_call` hooks (the voters, e.g. the
 known-names bundle or a config hook), which vote through `event[:guardrail]` (`deny!`, `ask!`) or the legacy
 `event[:blocked]` flag. A deny stays a deny for the hooks after it; a hook's ask is dropped when guardrails are
@@ -884,18 +1004,19 @@ Paths are under `lib/samagotchi/`.
 | `engine/model_settings.rb` | `Engine::ModelSettingsPart`: the session's model settings (SessionModelSettings) and the snapshots (EngineSnapshots), forwarded |
 | `engine/events.rb` | `Engine::EventsPart`: observers, `#announce`, the event lock, held announcements, load events, the emit helpers |
 | `engine/cards.rb` | `Engine::CardsPart`: `#show_card`, anytime commands and their threads |
-| `engine/objectives.rb` | `Engine::ObjectivesPart`: the objectives' view, proposals and audit |
+| `engine/objectives.rb` | `Engine::ObjectivesPart`: the objectives' stage builder, `announce_objectives` and `propose_objective` (forwarded), Check this's side request |
 | `engine/messages.rb` | `Engine::MessagesPart`: the session messages API (out-of-turn edits, checkpoints, the live conversation) |
 | `engine/plugins.rb` | `Engine::PluginsPart`: loading plugins, init tasks and staged tools, `Plugin::Host` |
 | `engine/hooks.rb` | `Engine::HooksPart`: turn-scoped hooks, the hook runtime (HookRoutes, forwarded), reminders |
 | `engine/guardrails.rb` | `Engine::GuardrailsPart`: the guardrails' readers and the first turn's load warnings |
 | `engine/participants.rb` | `Engine::ParticipantsPart`: the turn's author, a pair turn's stop, the participants line |
 | `engine/session.rb` | `Engine::SessionPart`: `#session=`, the state dir, the relay's view, the system prompt and its memory names |
-| `engine/verify.rb` | `Engine::VerifyPart`: Verify and Revise anchors at a turn's end, the verdict |
+| `engine/verify.rb` | `Engine::VerifyPart`: the Verify/Revise anchors' stage builder |
 | `engine/questions.rb` | `Engine::QuestionsPart`: ask-user-question (QuestionDesk, forwarded) |
-| `engine/toolkit.rb` | `Engine::ToolkitPart`: the toolkit, `ctx.load_tools`, System 1's toolkit suggestion |
-| `engine/context_judge.rb` | `Engine::ContextJudgePart`: the attached-context candidate judge and its cards |
-| `engine/turn_helpers.rb` | `Engine::TurnHelpersPart`: a turn's settings, images, model ref, used memories, the turn-end warm-up |
+| `engine/toolkit.rb` | `Engine::ToolkitPart`: the toolkit, `ctx.load_tools`, System 1's toolkit suggestion (the stage's builder and `warm_toolkit_suggestion!`, forwarded) |
+| `engine/context_judge.rb` | `Engine::ContextJudgePart`: the candidate judge's stage builder and `judge_late_candidates`, forwarded |
+| `turn_stages/toolkit_suggestion.rb`, `turn_stages/context_judge.rb`, `turn_stages/objectives.rb`, `turn_stages/warmup.rb`, `turn_stages/verify_anchors.rb` | `TurnStages::ToolkitSuggestion`, `TurnStages::ContextJudge`, `TurnStages::Objectives`, `TurnStages::Warmup`, `TurnStages::VerifyAnchors`: the turn stages ("Turn stages" above) |
+| `engine/turn_helpers.rb` | `Engine::TurnHelpersPart`: a turn's settings, images, model ref, used memories, the turn-end warm-up's stage builder |
 | `engine/turn_end.rb` | `Engine::TurnEndPart`: the normal ending and after-turn hooks, release, what an ending keeps, last_turn, the answer's display |
 | `event_fanout.rb` | `EventFanout`: how an event reaches the turn's sink and the observers (`emit_event`), the loops' stream handler, the working set's emit and dedupe; the Engine forwards |
 | `engine_snapshots.rb` | `EngineSnapshots`: the UIs' read model, `session_state_snapshot` (cheap, never raises) and `stats_snapshot` (may probe `/props`); the Engine forwards |