insika 0.8.0 → 0.9.0

data/docs/DEPLOY.md

@@ -188,7 +188,7 @@ insika doctor --json     # machine-readable (CI / monitoring)
 insika doctor --fix      # applies the safe autofixes and re-diagnoses
 insika env               # lists known keys + current values (secrets masked)
 insika tools:report      # tool audit over the stored traces: never-called
-                         # allowlisted tools, error rate > 30%, stale tools —
+                         # allowlisted tools, error rate > 30%, stale tools, gate refusals —
                          # read-only, the operator removes ([--agent ID] [--days N] [--json])
 ```
 
@@ -203,7 +203,18 @@ text rather than a serialized object** (a file whose content is a stringified Ha
 serves a mangled prompt on every turn while looking perfectly healthy — present,
 non-empty, and the agent still answers), **a prompt file that outgrew a prompt**
 (WARN past ~6 000 estimated tokens or 600 lines — the LLM-generated pack shape
-that costs 20%+ extra tokens per turn for no better instruction-following), and
+that costs 20%+ extra tokens per turn for no better instruction-following),
+**in-session compaction enabled with no model slot** (WARN — neither
+`compaction.model` nor the platform `utility_model` is set, so it can never run;
+see [Context](CONTEXT.md)), **eval seeding left on** (WARN — `evals.seeding`
+opens `POST /v1/conversations/:id/seed`, which writes a fabricated conversation
+state under the tenant token; fine while running snapshot evals, off in
+production — see [Evals](EVALS.md#state--a-case-starts-from-a-snapshot)),
+**provenance and presentation tools without an allowed evidence data tool**
+(WARN — the check only sees stored data declarations; verify any code-tool source),
+**fencing off for agents exposed by relay/widget environment configuration**,
+**cache-layer declarations** (known volatile providers marked identity are errors;
+custom identity providers need a byte-stability review), and
 **skill drift** — a shared skill whose
 body names one store, a prompt file routing to a skill the agent cannot load, a broken
 companion pair, a stale `eager:` key (see

data/docs/EVALS.md

@@ -42,6 +42,99 @@ expect:
 Turns replay **in order** under one conversation, so a case can build context ("what
 about the shipping?" after "I want the 70% bar"); the assertions run on the last turn.
 
+### State — a case starts from a snapshot
+
+Every case above starts from an **empty** conversation. To test "the customer already
+saw three products and says *add the second one*", such a case would first have to
+replay the search turn — which makes it depend on the model's first answer, costs a
+turn, and cannot reproduce a messy state (a contradiction from six turns ago, a
+stored preference). `state:` is the precondition, loaded into the conversation
+**before turn 1**:
+
+```yaml
+id: loja-chocolates-add-seen
+agent: loja-chocolates
+requires:
+  tools: [add_to_cart]
+state:
+  evidence:
+    ids: ["SKU-70-DARK"]
+    cards:
+      - { type: card, url: "https://shop.example/70", id: "SKU-70-DARK", caption: "Dark chocolate" }
+  memory: { facts: { preference: "dark chocolate" }, notes: [] }
+  history:
+    - { role: user, content: "quero chocolate amargo" }
+    - { role: assistant, content: "O chocolate 70% é SKU-70-DARK." }
+  briefing: { fields: { cep: "01311-000" } }
+turns:
+  - user: "adiciona uma unidade desse chocolate 70% no carrinho"
+expect:
+  tools_called: [add_to_cart]
+  never_calls: [search_products]
+  reply_omits: ["SKU-70-DARK"]
+```
+
+Only those four `state` keys are accepted by the case loader. A persona case may
+carry `state` too. Adapt the tool names, arguments and briefing fields to the agent.
+
+The evidence ledger is a runtime precondition, not a list shown to the model:
+include the relevant product and ID in `history` or the user's request. `cards`
+seeds the cards a search would have returned (each needs a `url` and an `id`; the
+id counts as seen), so a presentation case needs no lookup in the turn.
+
+With the HTTP transport, the eval stays a **client**: the runner never writes a
+store. Seeding goes through
+`POST /v1/conversations/:id/seed` (same Bearer as the turn, same id namespacing for a
+tenant), and the deployment accepts it **only while the platform setting
+`evals.seeding` is on** — off by default, because a seeded conversation is a
+fabricated precondition, and the doctor warns while it is on. With the setting off
+the replay Runner **skips** seeded cases with a reason; it also skips when its
+transport has no seed support. Other seed errors fail the replay. In-process
+`GraphTransport` dispatches `seed_session` directly and bypasses `evals.seeding`;
+it needs a runtime exposing the graph. The persona
+Simulator surfaces seed refusal as an error instead of the Runner's skip result.
+
+A session with messages returns `409`. Replays default to `eval-<case-id>`; pass
+`--conv-map FILE` with a JSON mapping such as
+`{"loja-chocolates-add-seen":"eval-add-seen-run-2"}` to use a fresh ID on reruns.
+Seeded memory may share a tenant cell even with fresh IDs; see
+[the seed API](API.md#seeding-an-eval-conversation) for scope and payload details.
+
+#### Graders — what a turn's calls and reply are checked against
+
+The turn's SSE stream reports each tool call with its arguments and how it ended
+(`ok`, `error`, or `blocked` plus the gate that held it), so the deterministic
+layer can check more than "was the tool called". All optional; each is its own
+check, and the report names the one that failed.
+
+| Key | Checks |
+|-----|--------|
+| `tools_called: [name, name?]` | each required tool was called (`?` = optional, never fails) |
+| `never_calls: [names]` | none of these was called — the negative every `tools_called` needs |
+| `calls_one_of: [names]` | at least one of these was called |
+| `first_tool: name` | the first call's name |
+| `max_tool_calls: N` | a ceiling on the turn's calls |
+| `reply_includes: [substrings]` | each appears in the published answer (case-insensitive) |
+| `reply_omits: [substrings]` | none appears — where an internal id, a CPF or a raw tag leaking into the customer's text is pinned |
+| `blocked_gates: ["tool:gate"]` | each pair appears among the turn's blocked calls |
+| `ui_components: [names]` | a presentation tool showed at least one card of each component (the `insika.ui` frames) |
+| `no_ui: true` | the turn showed nothing — the negative of `ui_components` |
+| `must_not: [detectors]` | the negative detectors (`pii_leak`, `tool_error`, …); a blocked call is not a tool error |
+
+**Every positive has a negative.** A case that only says `tools_called: [add_to_cart]`
+passes an agent that also re-searched, or that echoed the SKU to the customer. Pin
+what a correct turn does *not* do — `never_calls`, `reply_omits`, `max_tool_calls` —
+in the same case. Snapshots avoid the model calls needed to reconstruct the setup;
+use the simulator when later customer messages need to branch on the replies.
+
+`tools_called` confirms an attempted call, not a successful backend mutation.
+Arguments are collected for inspection; there is no generic argument or cart-state
+grader. `blocked_gates` needs completion statuses from the HTTP transport. The
+in-process `GraphTransport` records tool names and UI events, but not completion
+statuses or arguments. Neither transport counts `load_skill` / `load_knowledge` as
+tool calls. `ui_components` requires a nonempty selection; `no_ui`
+accepts absent UI events and events with zero items.
+
 ### `requires` — a case that cannot run here is skipped, not failed
 
 Deployments differ. Some stores have order tracking wired, some do not; some run
@@ -269,14 +362,11 @@ The model only sees `case_id`, enumerated with the ids the tool can actually run
 (never a free string it could invent) — every **simulated** case in the store, the same
 `persona:` shape as above.
 
-**Safety is derived here too, but there is no swap yet.** The tool computes the
-target's reachable side-effect tools (`Evals::EvalProfile`, the same derivation the CLI
-uses) and **refuses outright** — naming the tools — if that list is non-empty. Unlike
-the CLI, nothing here actually swaps a side-effect tool for a dry-run: `Evals::
-EvalProfile.registry` (the overlay) exists for exactly that, but nothing calls it yet.
-So `run_persona_eval` only runs against **read-only** target agents today; wiring the
-overlay into an in-process turn (so a target WITH a write tool can be tested safely) is
-follow-up work, not something this tool claims to do.
+**Side effects are replaced for local graph runs.** The tool derives the target's
+reachable side-effect tools and builds a throwaway executor with recorder tools
+under those names. Read-only tools and the other graph collaborators are shared.
+If side effects are reachable but no graph was supplied, it refuses the run.
+This substitution prevents real writes; it does not prove a backend mutation.
 
 **Budget**: the persona model + judge model calls are the cost of running the eval,
 charged to the **calling** agent's own turn — never the target's (the target's own

data/docs/FACTS.md

@@ -38,6 +38,10 @@ decides; the engine never applies its own proposal.
 5. Approved facts join the customer's memory cell and are injected by the
    Memory provider on the next turn of any session of that customer.
 
+The extraction transcript contains only nonblank `user` and `assistant` text,
+with original message indexes preserved. Tool payloads are excluded regardless
+of `fencing`; an assistant's repetition of tool text can still be included.
+
 ## Enabling it — the `distill:` block
 
 Distillation is pack data on the agent, exactly like `refinement:` or

data/docs/KNOWLEDGE.md

@@ -27,6 +27,13 @@ and an operator can see, edit and resolve all of it in the Studio. Only the
 optional FTS5 index remains, deferred with a measured trigger — see
 [What's not here yet](#whats-not-here-yet).
 
+Extraction reads only nonblank `user` and `assistant` text, retaining original
+message indexes. Direct tool payloads are excluded regardless of `fencing`;
+assistant paraphrases can still reach the extractor. The names and descriptions
+in the injected `<knowledge>` block are sanitized when
+[fencing](AGENTS.md#fencing--third-party-text-is-data-never-instructions) is on.
+The full body returned by `load_knowledge` is not fenced.
+
 ## The concept format
 
 One concept is one record — a markdown document with a YAML frontmatter

data/docs/OBSERVABILITY.md

@@ -25,15 +25,17 @@ authoring writes (`:golden_written`, `:agent_file_written`, …), queue bookkeep
 channel delivery (`:channel_delivered` — see [Channels](CHANNELS.md))
 travel the same stream and are **ignored** by the bridge: they open no span and
 touch no instrument, because they are not part of a turn's latency or cost. Any
-other subscriber still sees them. The one mid-turn event the bridge does consume
-is `:tool_loop_intervened` — it feeds the `insika.tool.loop_intervened` counter
-(no span: the intervention is a fact about the turn, not a timed operation).
+other subscriber still sees them. Additional events feed counters without opening
+spans: `:tool_loop_intervened`, `:tool_blocked` and `:context_compacted`.
 
 They are worth subscribing to even so, because each is the ONLY record of
 something that left no task of its own behind:
 
 | Event | Data | What it answers |
 |---|---|---|
+| `:tool_blocked` | `name`, `gate`, `param` | a provenance gate refused a call before execution; no rejected value in this event |
+| `:ui` | `component`, `title`, `items`, `count`, `dropped` | the presentation selection, including customer-facing card content; see [API](API.md#tool-and-presentation-sse-events) |
+| `:session_seeded` | `session_id`, `tenant`, `keys` | an eval snapshot was loaded; no snapshot contents |
 | `:turn_coalesced` | `task_id`, `merged`, `arrivals[]` | the fragments a customer typed in a row arrived as separate messages, and when |
 | `:turn_steered` | `task_id`, `count`, `total` | a message arrived mid-run and was appended to the turn in flight |
 | `:turn_steer_released` | `task_id`, `released_as`, `count` | the run could not absorb it, so it became the turn `released_as` |
@@ -70,8 +72,9 @@ and correct while the customer got nothing, because delivery is a separate,
 retried, out-of-band step. `status: "failed"` means the reply is sitting in the
 outbox and the customer is still waiting.
 
-Counts, ids and times only — never message content. The text lives in the
-transcript, which is the surface that is allowed to carry it.
+Operational audit events use metadata rather than transcript bodies. Presentation
+`:ui` events intentionally contain customer-facing card content; tool-call events
+can contain arguments. Do not treat the whole event stream as content-free.
 
 The bridge speaks the standard the market already runs on: point any OTLP backend
 at Insika and a real turn shows up as a full trace, next to counters and histograms
@@ -82,6 +85,14 @@ backend config, no vendor file. It ships a stable set of attribute and instrumen
 names, and the recipes below tell you what to chart against them — in whatever you
 already run.
 
+### Blocked tool calls
+
+`tool_blocked` carries `name`, `gate`, and `param`, with task/session correlation
+in event metadata. It never carries the rejected value. The `insika.tool.blocked`
+counter (unit `{call}`) uses the turn's agent/tenant/command labels plus
+`insika.tool` and `insika.gate`. Session traces keep the `gate` field alongside the
+masked result; `insika tools:report` lists blocked calls separately from errors.
+
 ## Contents
 
 - [Turning it on](#turning-it-on-opt-in-parity-when-off)
@@ -145,6 +156,7 @@ knows its outcome.
 | `insika.turn.duration` | histogram | `s` | same, when both timestamps are known |
 | `insika.tokens` | counter | `{token}` | the turn reported usage |
 | `insika.cost` | counter | `{USD}` | the turn's model is priced (see below) |
+| `insika.tool.blocked` | counter | `{call}` | a `tool_blocked` gate refusal |
 | `insika.tool.calls` | counter | `{call}` | a tool call completes |
 | `insika.tool.duration` | histogram | `s` | a `tool_call`/`tool_result` pair completes |
 | `insika.cache.hit_rate` | histogram | `%` | a turn reported billed prompt tokens (see below) |
@@ -291,7 +303,10 @@ climbing while `input` stays flat.
 `insika.tokens` filtered to `insika.token.type="cached"` over the same counter
 filtered to `input`. This is the number that moves your bill. For the per-turn
 distribution (does every turn hit, or do fleet averages hide cold agents?), chart
-`insika.cache.hit_rate` — p50 by `insika.agent`; a healthy agent sits near 100.
+`insika.cache.hit_rate` — p50 by `insika.agent`. Compare with that agent's baseline:
+cache eligibility, expiry and changing history affect the ratio. The
+[identity-prefix fingerprint](CONTEXT.md#the-observable-cache-fingerprints-and-the-invalidation-reason)
+explains identity/tool-schema changes; volatile category digests are separate.
 
 **Loop interventions**
 `insika.tool.loop_intervened`, rate, grouped by `insika.agent` and `insika.tool`.

data/docs/POLICY.md

@@ -34,7 +34,10 @@ Builtins cover tool-, skill-, and workflow-allowlisting, plus
 does not allow or deny but *tags* a tool as needing human approval. Set
 `approvals_required: [tool names]`; the gate then fires when the model tries to
 call that tool, suspending the turn until an operator approves it in the Studio.
-See [Security](SECURITY.md#human-approval).
+A data tool's `requires_evidence` check runs before this approval gate; an unknown
+ID is blocked without asking the operator. See
+[Tools](TOOLS.md#provenance-checking-ids-before-a-write) and
+[Security](SECURITY.md#human-approval).
 
 ## Layer 3: Guardrails (content safety)
 

data/docs/RELEASING.md

@@ -19,6 +19,10 @@ is invisible to it. Do not publish on rspec alone.
 3. Every new `lib/` file is **tracked in git**. The gemspec's `files` come from
    `git ls-files`: an untracked file builds without a warning and the installed
    gem fails at `require` — this is exactly the failure this proof exists to catch.
+4. If changing the `fencing` default (currently off), first run the deployment's
+   golden cases with it enabled, retain the comparison report, and document the
+   behavior change in `CHANGELOG.md`. A default change needs evaluation evidence;
+   a scheduled version number alone is not the release gate.
 
 ## Cut the gem
 

data/docs/SECURITY.md

@@ -205,6 +205,32 @@ category: the agent's category reply → the agent's default → the builtin
 category → the builtin default. All of it is editable in the Studio Configuration
 form. See [Agents §Layer 3](POLICY.md#layer-3-guardrails-content-safety).
 
+## Third-party text is data (fencing)
+
+Input guardrails cover the incoming message. The opt-in `fencing` flag also
+sanitizes ordinary tool result strings, memory text and the injected knowledge
+names/descriptions, and places a
+fixed notice under the identity. It reduces known markup and Unicode tricks;
+it does not make arbitrary third-party instructions safe.
+
+The user/assistant-only extraction filter applies even when fencing is off.
+Attachment captions and `load_knowledge` bodies are not fenced. The extraction
+filter excludes direct tool messages,
+but assistant paraphrases can still become extraction input. See
+[Agents](AGENTS.md#fencing--third-party-text-is-data-never-instructions) for the
+exact scope, exceptions, default and size cap.
+
+## Write provenance and serial execution
+
+A data tool's `requires_evidence` gate checks IDs against the session ledger
+before approval or backend execution. A known ID proves a prior lookup; it does
+not authorize access or establish current stock, price or quantity limits.
+Those checks remain the backend's responsibility.
+
+Tools marked `side_effect` execute one at a time within a session, including in
+parallel batches. This is not a cross-session or distributed backend lock.
+See [Tools](TOOLS.md#provenance-checking-ids-before-a-write).
+
 ## Human approval
 
 Some tool calls should not happen unattended. Mark them with
@@ -242,7 +268,7 @@ defense-in-depth: without it, `ALLOW_PRIVATE` opens *any* private destination.
 > the request never leaves the process, and the conversation *looks* fine. Verify
 > tool health by the Studio session **trace** (a healthy call shows the backend's
 > `200`), never by the model's reply. Full detail in
-> [Tools §Egress](TOOLS.md#egress-the-ssrf-guard-and-its-silent-failure).
+> [Tools §Egress](TOOLS.md#egress-the-ssrf-guard).
 
 ## Sandbox: confined execution
 

data/docs/TOOLS.md

@@ -12,10 +12,10 @@ kinds, and the distinction that matters is **who can change one at runtime**:
 
 | | **Code tool** | **Data tool** | **MCP tool** |
 |---|---|---|---|
-| What | a Ruby class (`< RubyLLM::Tool`) | an HTTP call described by config, no Ruby | an MCP server's tool, called LIVE |
+| What | a Ruby class (`< RubyLLM::Tool`) | an HTTP call or card presentation described by config | an MCP server's tool, called LIVE |
 | Lives | in the deployment image | as a row in SQLite | on the MCP server, behind a live client |
 | Editable at runtime | no (shipped in the image) | **yes** (DSL / API / manifest / Studio) | **yes** — enable/edit the *instance* (DSL / CLI / API / JSON import / Studio); the server owns its own tools |
-| Reach for it when | logic must run in-process (file edit, shell, subagent) | calling an external HTTP API | adopting a whole external MCP server's toolset |
+| Reach for it when | logic must run in-process (file edit, shell, subagent) | calling an HTTP API or selecting evidence cards | adopting a whole external MCP server's toolset |
 
 **MCP tools are not data tools.** Configuring an enabled MCP **instance** (any
 surface below) is enough — its tools appear automatically, tagged
@@ -120,7 +120,7 @@ once, at ingestion — see the gotcha below before reaching for it:
   (`object/array/string/number/integer/boolean`); `oneOf`/`anyOf`/`allOf`/`$ref`/
   `if`/`then`/`else` are forbidden (not every provider supports them).
 - `side_effect` defaults from the method (GET/HEAD → false, else true) and drives
-  checkpoint/replay semantics (a completed side-effecting tool is not re-run on
+  serial execution within a session and checkpoint/replay semantics (a completed side-effecting tool is not re-run on
   resume — see [Architecture](ARCHITECTURE.md#durability-checkpoints-and-resume)).
 
 ### `halt_when`: when the answer is already out
@@ -199,12 +199,10 @@ backend, not of whoever calls it. Every agent sharing the tool gets the same val
 
 ## Evidence: the lean envelope and grounding
 
-A catalog tool returns products; the model should only ever quote the ones the tool
-actually returned — the store dies of a SKU the model invented. `evidence` is the
-declaration that makes "no claim without a tool ID" an engine rule instead of a
-prompt convention. One declaration does **both** jobs: the engine strips the result
-down to what the model sees (the lean envelope) **and** records every returned id on
-the session's evidence ledger. There is no "lean but not evidence" mode.
+An `evidence` declaration reshapes a tool result into a lean list and records its
+IDs in the session ledger. The ledger supplies the write gate, presentation tools
+and optional output grounding below. Declaring evidence alone does not prevent
+unsupported claims in the final answer.
 
 ```jsonc
 { "name": "search_products",
@@ -226,14 +224,63 @@ the session's evidence ledger. There is no "lean but not evidence" mode.
   never a null. A malformed evidence result becomes `{ "error": … }` back to the
   model — a correctable tool answer, exactly like a malformed call.
 - **Attachments** are the optional second half: `[{ "type": "card"|"image",
-  "url": "…", "caption": "…" }]` (≤ 16, url ≤ 500 chars, malformed dropped). They
+  "url": "…", "caption": "…", "id": "…" }]` (≤ 16, url ≤ 500 chars, malformed dropped). They
   **never** reach the model context or the transcript — they ride the channel
   delivery as an additive `attachments` key on the outbox payload, and the channel
-  (or its consumer) decides what a card looks like.
+  (or its consumer) decides what a card looks like. Supply an explicit `id` when
+  cards are not one-to-one with items in the same order. Without one, an attachment
+  takes its item's ID at the original position, before malformed cards are dropped.
+- Lean `line` passes through the tool-result sanitizer only when `fencing` is on.
+  Attachment captions are normalized to UTF-8 but are not fenced. See
+  [Fencing](AGENTS.md#fencing--third-party-text-is-data-never-instructions).
 - A **code tool** opts in the same way: it either returns `{ items, attachments }`
   directly and declares `evidence` in its registry metadata, or exposes an
   `evidence` reader. No declaration = today's tool behavior, byte for byte.
 
+### Provenance: checking IDs before a write
+
+Declare `requires_evidence` on a data-defined tool to accept only IDs previously
+returned by an `evidence` tool in the same session:
+
+```json
+{ "requires_evidence": ["product_id"] }
+```
+
+The full form is `{ "requires_evidence": { "params": ["product_id"] } }`.
+The list must be non-empty and name declared top-level parameters. Scalar values
+and every element of an array are converted to strings and compared exactly:
+`SKU-1` and `sku-1` are different IDs. IDs typed by a customer do not count.
+The ledger includes earlier turns and completed evidence results in the current
+turn, capped at the latest 1,000 distinct IDs. Every declared parameter the call
+carries must pass before any write occurs; a parameter the schema marks optional
+and the model leaves out has nothing to check, a required one left out blocks.
+Search first, then write in a later batch: a search and write in the same parallel
+batch have no dependency ordering guarantee.
+
+An unknown ID returns `status: "blocked"`, `gate: "provenance"`, the parameter,
+the value, and an instruction to search or look it up before retrying. The backend
+is never called and no operator approval is requested. A missing ledger blocks the
+call too. Omit the declaration to keep the existing behavior; MCP tools do not
+support this declaration.
+
+The Studio tool editor exposes `requires_evidence`. Blocked calls appear in session
+traces and `insika tools:report`, emit `tool_blocked` with name/gate/parameter only,
+and increment `insika.tool.blocked`. `insika doctor` warns when an agent allows a
+gated data tool without an allowed data tool declaring `evidence`.
+
+### Side effects in parallel batches
+
+With `limits.tool_concurrency > 1`, tools marked `side_effect` execute one at a time
+within the session's runtime. Unmarked tools still run concurrently, including
+while a write is running. MCP tools are marked `side_effect: true` unless the server
+annotates them `readOnlyHint`; a read-only `POST` data tool needs an explicit
+`"side_effect": false` to keep its concurrency.
+A queued write holds no concurrency slot. Different sessions remain independent;
+backend rules such as quantity limits remain the backend's responsibility.
+
+The per-tool timeout starts after both gates are acquired. Trace duration includes
+queueing time, so it measures how long the model waited, not just backend execution.
+
 ### Grounding: policing claims against the ledger
 
 With the ledger fed, the pack declares how claims are policed — data on the agent,
@@ -263,11 +310,63 @@ grounding mode: :flag, matcher: { sku: '\b[A-Z]{2,4}\d{4,8}\b' }
 - Grounding is **independent of the guardrails opt-in**: an agent with guardrails
   off and `grounding.mode: :flag` still gets the check.
 
+## Presentation tools: the model picks ids, the engine shows the cards
+
+A **presentation tool** selects which evidence cards to show. Declare it with
+`presentation` instead of `request`; it runs in-process and is always
+`side_effect: false`. The model supplies IDs, never card URLs or captions.
+
+```jsonc
+{ "name": "present_products",
+  "description": "Show product cards to the customer. Pass only ids a search returned.",
+  "parameters": [{ "name": "product_ids", "type": "array:string" },
+                 { "name": "title", "type": "string", "required": false }],
+  "presentation": { "component": "product_cards",   // what the channel renders
+                    "ids": "product_ids",           // the array:string parameter
+                    "max": 8 } }                    // 1..16 (the attachment cap; default 16)
+```
+
+Exactly one of `request` / `presentation`; `ids` must name a declared `array:string`
+parameter; `component` follows the tool-name rule. Create it through the DSL,
+manifest or API. The Studio form preserves an existing `presentation` declaration
+on save but does not expose its fields. Requested IDs are deduplicated in order
+and compared case-sensitively. The engine then:
+
+1. keeps only ids the session's **evidence ledger** has seen — the rest are dropped
+   with reason `unknown` (an id the model invented, or the customer typed);
+2. joins each kept id to the card an evidence tool returned **this session** — this
+   turn's first, then the last 64 the ledger kept (cards carry the `id` of the item
+   they stand for); a known id with no card is dropped with reason `no_card`;
+3. truncates to `max` — the overflow is dropped with reason `max`;
+4. records the selection on the turn and emits `:ui` on the stream (published as
+   `insika.ui` on `/v1/responses`, as the `ui` frame on the web channel);
+5. answers the model with `shown` (IDs) and `dropped` (objects with `id` and `reason`) — plus one
+   instruction when nothing could be shown ("name the products in text or search
+   again").
+
+**Delivery.** When a turn made a presentation call, the outbox `attachments` are
+*exactly the presented cards*, in call order, each stamped with the call's `component`
+and `title`. A turn with no presentation call delivers every hoarded card, as before —
+a pack that declares no presentation tool sees no change. An empty selection also
+suppresses that fallback: it emits `count: 0` and delivers no cards from that call.
+An earlier turn's ID can be shown without a fresh lookup while its card remains
+in the session's 64-card ledger. IDs and cards have separate caps: a known ID can
+still return `no_card`. Cards are stored snapshots, not a stock or price refresh.
+
+A presentation tool needs an evidence source to populate the session's cards.
+`insika doctor` warns when an agent allows presentation without an allowed evidence
+data tool (`presentation-tools`); it cannot verify a code-tool evidence source. The line that tells the model
+*when* to show cards ("show cards with present_products, ids only") is the pack's.
+
+Not here: partial rendering while arguments stream, per-component enrichment (price
+today, stock — the card is what the evidence tool returned), and a second component
+such as suggestion chips (same mechanism, when a channel asks for it).
+
 ## Registering a tool
 
 A tool appears in the Studio panel and enters an agent's tool-loop when it is
 **registered** in the catalog **and** allowed by the agent's policy allowlist.
-Four ways to write a data tool into the store — all **hot** (registry and catalog
+Three ways to write a data tool into the store — all **hot** (registry and catalog
 reload, no restart):
 
 1. **DSL** — `data_tool(name:, …)` in a `Insika.agent { … }` block.
@@ -275,8 +374,6 @@ reload, no restart):
 3. **Manifest** — `POST /v1/tools/manifest`. Partial failure is isolated: one
    malformed tool becomes an `errors[]` entry; only a structural manifest error
    fails the whole request. The response reports `{ version, created, updated, errors }`.
-4. ~~MCP ingestion~~ — retired. An MCP server's tools are no
-   longer written into this store at all; see [MCP servers](#mcp-servers).
 
 ### The one gotcha: env/secret templating is manifest-only
 
@@ -298,7 +395,7 @@ at turn time, not ingestion).
 An MCP **instance** is durable config — transport, target, credentials, an
 `enabled` flag — held in its own store, separate from data tools. Once an
 instance is enabled, its tools appear in the catalog automatically (group
-`mcp:<instance>`, `side_effect: true`), and every call goes straight to the
+`mcp:<instance>`, `side_effect: true` unless annotated `readOnlyHint`), and every call goes straight to the
 server through a live, held client — the runtime never converts an MCP tool
 into a stored data tool.
 
@@ -405,9 +502,10 @@ held client, which does its own discovery on first use regardless of whether
 A model can ask for several tools in one step. By default the engine runs them one
 at a time. Set `limits[:tool_concurrency]` above 1 (see
 [Agents](AGENTS.md#tool_concurrency--parallel-tool-calls)) and the calls in that
-batch run concurrently, **at most N in flight**, on the turn's own reactor — so
-the wall-clock of a batch of slow data tools approaches the slowest call rather
-than their sum. The cap covers every enveloped tool of the turn, including the
+batch run concurrently, **at most N in flight**, on the turn's own reactor.
+Tools marked `side_effect` still execute one at a time per session; queued writes
+acquire that serial gate before taking a shared concurrency slot. See
+[Side effects](#side-effects-in-parallel-batches). The cap covers every enveloped tool, including the
 ones `tool_search` promotes mid-turn.
 
 It applies only to what the *model* fans out. Two primitives already parallelize
@@ -434,7 +532,7 @@ Turning it on changes three things, all of them worth knowing before you do:
 Approvals and concurrency are mutually exclusive per turn — the approval gate wins
 and the turn goes serial. That is a deadlock avoided, not a preference.
 
-## Egress: the SSRF guard (and its silent failure)
+## Egress: the SSRF guard
 
 Data tools make outbound HTTP, so every call passes through the **EgressGuard**, a
 Server-Side Request Forgery defense. The default posture is **strict: public
@@ -446,17 +544,10 @@ Server-Side Request Forgery defense. The default posture is **strict: public
 | `INSIKA_EGRESS_ALLOW_HTTP=1` | permit plain `http` — **loopback dev only** |
 | `INSIKA_EGRESS_ALLOW_PRIVATE=1` | permit private/loopback IPs — **dev only** |
 
-> ⚠️ **Egress failures are silent.** When a tool targets a blocked host (e.g. a
-> plain-`http` localhost backend without the opt-ins), the guard turns the block
-> into a `{ error: … }` returned **to the model** — the request never leaves the
-> process, yet the stream still emits a tool call, so the model narrates a
-> plausible failure and the conversation *looks* like it worked. You will not see
-> an exception.
->
-> **Always verify by the trace, never by the reply:** open the Studio session
-> viewer — a healthy call shows the request, args, and the backend's `200`; a
-> missing or errored call is almost always egress (host not in the allowlist, or
-> `http`/private without the opt-in).
+An egress rejection returns `{ error: … }` to the model without making the HTTP
+request. Inspect the session trace for the actual error; a plausible reply does
+not prove the backend ran. Provenance refusals instead report `status: "blocked"`
+and `gate: "provenance"`.
 
 Egress is **orthogonal** to registration and allowlisting: a tool can be
 registered, allowed, offered to the model, and still blocked at call time.
@@ -471,8 +562,9 @@ Work down this checklist:
    `data-tools` check is the only place that says so.
 2. **Allowed for this agent?** In `tools_allow` (or an allowed group), and not in
    `tools_deny`?
-3. **Egress?** If it *appears and is called* but "fails", open the trace — a
-   blocked call is ~99% egress.
+3. **Call refused or failed?** Inspect the trace. For `gate: "provenance"`, look up
+   the ID through an evidence tool before retrying. For an error, check its message
+   for schema, egress, timeout or backend failures.
 4. **URL literal?** For non-manifest tools, an unresolved `{{env.*}}` would have
    422'd at import — re-check the definition.
 
@@ -490,7 +582,7 @@ routes, the signed link and the retention/LGPD reach.
 The per-session trace answers "what did this conversation call"; nothing used to
 answer "what does this agent carry and never use". The report aggregates the
 stored traces per agent (tasks → sessions → `tool_traces`, the same read the
-Studio does) and flags three shapes:
+Studio does) and flags four shapes:
 
 - **`never_called`** — in `tools_allow`, zero calls in any stored trace. Dead
   weight: its schema ships on every request and buys nothing.
@@ -498,6 +590,8 @@ Studio does) and flags three shapes:
   the window (default 14 days). Either the tool is broken or the model cannot
   hold its contract.
 - **`stale`** — called at some point, but not once inside the window.
+- **`blocked`** — gate refusals in the window, counted by gate. These do not count
+  as conventional tool errors.
 
 ```bash
 insika tools:report                        # every stored agent

data/docs/prompts/ADD-TOOL.md

@@ -30,6 +30,7 @@ with one turn. Nothing more.
 | The need | The kind | Where it lives |
 |---|---|---|
 | Call an external HTTP API | **data tool** (`data_tool` in the DSL block) | a row in SQLite, editable at runtime |
+| Show selected evidence cards | **presentation data tool** (`presentation`, no `request`) | the tool store; see [Tools](../TOOLS.md#presentation-tools-the-model-picks-ids-the-engine-shows-the-cards) |
 | Logic must run in-process | **code tool** (a Ruby class `< RubyLLM::Tool`) | the deployment image |
 | Adopt a whole external MCP server | **`mcp` instance** | durable config; its tools appear tagged `mcp:<name>` |
 | Teach a procedure (no data fetching) | **skill** (`skill "name", description:, instructions:`) | loads on demand via `load_skill` |
@@ -78,6 +79,12 @@ RULES:
   verbatim and arguments are checked against it at call time.
 - Author the FINAL url: the HTTP client does not follow redirects, and the egress guard
   cleared that host only.
+- For a write that accepts catalog IDs, declare `requires_evidence` for those
+  parameters and ensure an allowed lookup declares `evidence`. Mark the write
+  `side_effect: true`; the engine serializes marked writes within a session.
+- For presentation, follow the [card contract](../TOOLS.md#presentation-tools-the-model-picks-ids-the-engine-shows-the-cards):
+  pass known IDs to the presentation tool. Look up again if their cards are absent
+  from the session ledger or current information is needed.
 - Do not add a second capability "while we're here".
 
 ## Step 3 — Make sure it enters the tool-loop
@@ -96,8 +103,11 @@ instead of fighting it.
 ## Step 4 — Prove it with ONE turn
 
 Run one `reply()` whose message forces the call ("how many BRL is 1 USD right now?").
-The reply must use what the tool returned — if the model answers from imagination, the
-tool did not run: re-check Step 3 before touching the prompt.
+Inspect the trace to confirm the call and result; the reply alone is not proof.
+For a gated write, also verify that an unknown ID is blocked before any backend
+request. For presentation, verify the selected `insika.ui` items. Use
+[snapshot eval assertions](../EVALS.md#graders--what-a-turns-calls-and-reply-are-checked-against)
+when the flow needs a repeatable precondition.
 
 ## Step 5 — Self-check
 

data/docs/prompts/DIAGNOSE-TURN.md

@@ -43,6 +43,9 @@ text), roughly **when**, and expected vs. actual. Reproduce once locally if chea
 | turn completed, customer got nothing | delivery is separate from the turn: check `channel_delivered` / `delivery_failed` | [Channels](../CHANNELS.md) |
 | freshly created agent returns empty turns | persona overflows the default `context_budget` (8000) | [Context](../CONTEXT.md) |
 | tool never called (or "missing") | not registered OR not allowed (`tools_allow`) | [Tools](../TOOLS.md) § troubleshooting |
+| `tool_blocked` with `gate: provenance` | ID absent from session evidence; look up before retrying | [Tools](../TOOLS.md#provenance-checking-ids-before-a-write) |
+| presentation shows no cards | inspect dropped IDs: `unknown`, `no_card`, `max`; a known ID may have no retained card | [API](../API.md#tool-and-presentation-sse-events) |
+| cache reuse dropped | compare identity/tool-schema fingerprints with provider cache token accounting | [Context](../CONTEXT.md#the-provider-prefix-cache) |
 | identical `tool_call` repeated, then abort | the `max_tool_repeat` loop guard | [Agents](../AGENTS.md) § limits |
 | model gave up after one empty result | `tool_persistence` off (it is ON by default) | same |
 | `turn_stuck` event | the agent declared it cannot proceed — escalation signal, not a bug | [Agents](../AGENTS.md) § stuck |

data/docs/prompts/GO-LIVE.md

@@ -87,7 +87,9 @@ In order, each with evidence:
 
 1. `curl https://<host>/up` → `{"status":"ok"}`.
 2. `bin/insika doctor` against the deployed volume (or via the platform's shell) —
-   relay its findings verbatim; fix errors before continuing.
+   relay its findings verbatim; fix errors before continuing. Check evidence sources
+   for gated writes/presentation, review the fencing warning, and leave
+   `evals.seeding` off after snapshot evals. See [Deploy](../DEPLOY.md#strict-config-and-insika-doctor).
 3. One authenticated turn:
 
 ```bash