@orkestrel/scaffold 0.0.68 → 0.0.70

package/dist/host/guides/ollama.md

@@ -111,7 +111,7 @@ These invariants hold across `src/core` ↔ `ollama.md`. The engine contract its
 
 1. **Doc ↔ source bijection.** Every `function` / `class` / `const` / `interface` / `type` row in the `## Surface` table is a real export of the `src/core` surface, and every export appears as a Surface row — exhaustive, both directions.
 2. **Imports each boundary from its owner, no cycle.** `OllamaProvider` extends `AgentProvider` and implements `AgentProviderInterface`; that base, `ProviderRequest`, `ProviderIncrement`, `ProviderParserInterface`, `ProviderInterface`, `ProviderOptions`, and `Message` come from `@orkestrel/agent`. `createNDJSONParser` comes from `@orkestrel/ndjson`, `ToolCall` from `@orkestrel/tool`, `TokenUsage` from `@orkestrel/budget`, and the guards (`isRecord` / `isString` / `isNumber` / `parseJSONAs`) from `@orkestrel/contract`. The provider errors are owned by `@orkestrel/agent` and `ToolDefinition` by `@orkestrel/tool`: `src/core` imports neither, and both reach a caller through the base — the base throws the errors this wire's failures become, and it accepts the `ToolDefinition[]` a call advertises. Each dependency is one-way and never imports from `@src/core`. No module under `src/` imports `@orkestrel/timeout` — the base arms the deadline — and the manifest declares it as a development dependency for the guide's bounding pattern, which imports it as a consumer would.
-3. **The `/api/chat` wire body.** `OllamaProvider` POSTs to `${url}${OLLAMA_CHAT_PATH}`, defaulting `url` to `DEFAULT_OLLAMA_URL` and `keep_alive` to `DEFAULT_KEEP_ALIVE`. The body carries `model`, the mapped `messages`, `stream: true` on every call, `keep_alive`, and `think` (the per-call `ProviderStreamOptions.think` override when present, else `OllamaOptions.think`, default `false`), adding `options` only when configured, `format` only when the call supplies a `ProviderStreamOptions.schema`, and `tools` only when a non-empty `ToolDefinition[]` is passed. Each tool maps to `{ type: 'function', function: { name } }`, with `description` and `parameters` added only when the corresponding `ToolDefinition` fields are supplied. Messages map to the wire's minimal `{ role, content }` turn, with `tool_calls` added only on a turn that replays them and `images` only on a multimodal turn. A non-OK status is the base's failure, not this package's: it throws `ProviderError` with code `'HTTP'`, the response `status`, and a message bounded to an excerpt of the response body.
+3. **The `/api/chat` wire body.** `OllamaProvider` POSTs to `${url}${OLLAMA_CHAT_PATH}`, defaulting `url` to `DEFAULT_OLLAMA_URL` and `keep_alive` to `DEFAULT_KEEP_ALIVE`. The body carries `model`, the mapped `messages`, `stream: true` on every call, `keep_alive`, and `think` (the per-call `ProviderStreamOptions.think` override when present, else `OllamaOptions.think`, default `false`), adding `options` only when configured, `format` only when the call supplies a `ProviderStreamOptions.schema`, and `tools` only when a non-empty `ToolDefinition[]` is passed. Each tool maps to `{ type: 'function', function: { name } }`, with `description` and `parameters` added only when the corresponding `ToolDefinition` fields are supplied. `title` and `annotations` are **never sent**: the `/api/chat` tool function object carries no field for either. Messages map to the wire's minimal `{ role, content }` turn, with `tool_calls` added only on a turn that replays them and `images` only on a multimodal turn. A non-OK status is the base's failure, not this package's: it throws `ProviderError` with code `'HTTP'`, the response `status`, and a message bounded to an excerpt of the response body.
 4. **Configurable `think` on the wire; the base's splitter keeps the assembled content clean.** For a thinking-capable model (for example `qwen3`) the per-request `think` flag is the only wire-level reasoning control (its native renderer honours neither the qwen3 `/no_think` token nor a Modelfile `PARAMETER think false`). It is configurable through `OllamaOptions.think` (default `false` — so the general-purpose provider stays immediate for non-thinking models and tests fast) and overrideable per call through `ProviderStreamOptions.think`. Set `think: true` when the caller displays reasoning separately from the answer: the daemon then separates reasoning natively, returning it on the distinct `message.thinking` channel, which `read` reports and the engine yields as `ProviderDelta` `{ channel: 'thinking', text }` and accumulates onto `ProviderResult.thinking`. Either way the base's `split` behaviour stays armed, because a daemon may ignore `think: false` for a thinking model and render reasoning inline as `<think>…</think>` content; `OllamaProvider` passes no `split` to `super`, so the default separation applies and the assembled `content` is the splitter's clean accumulation. The reasoning never re-enters the conversation.
 5. **One NDJSON path.** Every call consumes NDJSON — one JSON object per `\n`-terminated line. `frame()` returns `createNDJSONParser()`, fresh per call, so no call inherits another's half-read record, and the base pairs it with a streaming `TextDecoder` so a record split across byte reads is reassembled. At end of input the base calls `finish(parser)`, which feeds a trailing `\n` through the parser: a non-conformant proxy's final unterminated line is recovered rather than silently dropped. `OllamaProvider` passes no `strict` to `super`, so a stream that ends without a settled record still assembles its result from the deltas it carried.
 6. **`stream` yields deltas and returns the assembled result.** The engine yields each non-empty clean content delta as `{ channel: 'content', text }` and each daemon-side reasoning delta as `{ channel: 'thinking', text }`; its return value is the assembled `ProviderResult` whose `content` is the splitter's authoritative clean accumulation — the concatenation of the yielded content deltas, except across an implicit-open reclassification, where the reasoning prefix had already streamed before a bare `</think>` revealed it and the yields cannot be recalled — plus any tool calls collected across lines, the usage from the `done` line, and the separated `thinking` when the turn produced any.
@@ -121,7 +121,7 @@ These invariants hold across `src/core` ↔ `ollama.md`. The engine contract its
 10. **The base owns everything that is not the wire.** The per-call deadline (`OllamaOptions.timeout`, `120_000`ms when omitted, folded with the caller's signal so either cancels the request and the timer is always cleared), the cancellation rule (a `stream` cancelled mid-flight throws `ProviderAbortError` carrying the partial, and the reader and parser are released in a `finally`), the transport seam (`OllamaOptions.fetch` and the per-request `OllamaOptions.headers` hook, awaited inside the deadline and raced against the combined signal), and the bounded error read all live in `AgentProvider`. `OllamaOptions` extends `ProviderOptions`, so those keys are the base's and behave identically for every provider built on it; [`agent.md`](agent.md) states each rule once.
 11. **Context-framing `format` (provider-default cascade level, expose-only).** `OllamaOptions.format` is an optional `ContextFormat` (from `@orkestrel/agent`) — the provider's context-framing default, passed to `super` and exposed as `provider.format`. It is the provider-default level of the `AgentContext` build cascade (beats the managers' built-in framing, beaten by a manager-options or per-item override; see [`agent.md`](agent.md)), read by the Agent when it assembles the prompt. Omitted ⇒ `undefined` (framing-agnostic; core's built-in framing applies unchanged). It is **never sent on the `/api/chat` wire**: it is consumed by core, absent from the request `body`, and unrelated to Ollama's structured-output `format` parameter — that one is sent in the request `body`, but only when a per-call `ProviderStreamOptions.schema` is supplied — the framing default and that wire parameter only share a word.
 12. **Event-free.** A pure functional boundary — no Emitter, no events. Each call is a function of its arguments.
-13. **A core face that runs in a browser.** The package publishes the `.` entry alone, built from `src/core`, which imports no `node:*` module and no DOM global; the scoped core typecheck compiles it with the `ESNext` and `WebWorker` libraries and no ambient `@types`, so neither Node's globals nor the DOM's are in scope, and the base binds `globalThis.fetch` to its own receiver so a browser does not throw `Illegal invocation` on a bare transport reference. On 2026-09-14 in Chrome 148 the built `@orkestrel/ollama` core entry and its whole `@orkestrel` import closure loaded as ES modules with no console error: `OllamaProvider` drove the local daemon directly for a settled answer carrying its usage counts, a cancel mid-stream returned `ProviderAbortError` holding the partial that had streamed, and the same page reached that daemon through a `createRelay` server, where a wrong bearer arrived as `ProviderError` with code `'HTTP'` and status `401`. The daemon is the remaining limit — a page reaches `/api/chat` directly only where the daemon, or a proxy in front of it, answers the page's origin; otherwise relay the call through your own server ([Relaying through your own server](#relaying-through-your-own-server)).
+13. **A core face that runs in a browser.** The package publishes the `.` entry alone, built from `src/core`, which imports no `node:*` module and no DOM global; the scoped core typecheck compiles it with the `ESNext` and `WebWorker` libraries and no ambient `@types`, so neither Node's globals nor the DOM's are in scope, and the base binds `globalThis.fetch` to its own receiver so a browser does not throw `Illegal invocation` on a bare transport reference. [`tests/service/page.test.ts`](../tests/service/page.test.ts) gates that claim rather than recording it: it launches the host's own Chrome or Edge through `@orkestrel/browser`, serves the built `@orkestrel/ollama` core entry and its whole `@orkestrel` import closure from an import map on a `127.0.0.1` fixture, and reads the page's requests from the browser's own request log. The page loads with no uncaught error and no console error, on the recorders a deliberate page fault then makes report; an `Agent` holding a page-defined DOM-writing `Tool` completes a tool loop against the live daemon through a same-origin `createRelay` server, where the model's recorded call reaches the page, the tool's minted receipt is read back out of the real DOM and found again as the `role: 'tool'` message of the relay request and the `/api/chat` request that follow the turn the call was dispatched in, and the run settles with `partial: false`; the page issues exactly one `POST /inference` per turn and nothing else across the whole operation window, with a deliberate `/control` request proving such a window can report one; a wrong bearer arrives as `ProviderError` with code `'HTTP'` and status `401` with no daemon request made; and `createOllama` in the page answers a prompt over `/api/chat` on the daemon's own origin after `requireDaemonOrigin` confirms the daemon permits the page's origin. Each attempt ends within its allowance plus its release share, so nothing the attempt schedules outlasts the case that holds it. The attempt's signal cancels the part of the connection the installed `BrowserOptions.signal` races — discovery, the port-free check, the launch, and `client.connect()` — and the attempt's own race is what bounds every phase after that, the target listing the connection ends with included; [`tests/service/page.test.ts`](../tests/service/page.test.ts) and the `PAGE_BOUNDS` table it spends state the mechanism. The model's choice to call a tool is retried at most 3 times, and that choice is the only reading another attempt buys: every attempt retains its observations before any page read can throw, and only a run that completed an answer without dispatching the tool spends another launch. An acquisition, read, release, or run failure ends the retry, and so does a run that deadline interrupted before it settled — an interrupted run reports no tool call for a reason another launch cannot clear, so retrying it would report the exhaustion as the model never choosing the tool. The request accounting is asserted over each retained attempt, so what the gate establishes is that the model called the tool within those attempts and that no attempt's traffic went unread. The daemon is the remaining limit — a page reaches `/api/chat` directly only where the daemon, or a proxy in front of it, answers the page's origin; otherwise relay the call through your own server ([Relaying through your own server](#relaying-through-your-own-server)).
 14. **Tested live against a real local Ollama (no `skipIf`).** The live tests run against a real Ollama daemon — no mocks, only genuine third-party calls — model `qwen3.5:2b-q4_K_M`, with `OLLAMA_HOST` / `OLLAMA_MODEL` overridable. Unlike the other surfaces, the dedicated `service` project requires the daemon: `tests/setupService.ts` throws a clear error if it is unreachable and warms the model (a `num_predict: 1` chat) before the suite, so the live tests run unconditionally (no `describe.skipIf`). The project runs serially (`fileParallelism: false`) with a 120s test/hook timeout so a cold load cannot flake it; `keep_alive` keeps the model resident across files, and `bash scripts/ollama.sh` brings the daemon and model up before the battery in CI. Assertions are structural — they hold whatever wording a small model produces — and never pin exact output. The hermetic half sits in `tests/src/core/`, and the relay round trip is proved hermetically in [`tests/src/core/integration.test.ts`](../tests/src/core/integration.test.ts) and live in [`tests/service/relay.test.ts`](../tests/service/relay.test.ts).
 15. **Doc ↔ source method bijection.** The `## Methods` table lists exactly the members `OllamaProvider` declares — `frame`, `body`, `read`, and `finish` — and the class declares exactly those. `generate` and `stream` reach a caller through the same class but are declared once, in `AgentProvider`, and documented in [`agent.md`](agent.md).
 
@@ -198,7 +198,7 @@ provider.finish(parser) // [] — the parser held nothing back
 
 ### Running in the browser
 
-The published face is core, so the same `createOllama` call runs unchanged in a browser module. Point `url` at whatever the page can actually reach: the daemon's own origin where it answers that origin, or your own server standing in front of it. A page that reaches a daemon directly is a development arrangement — it puts the model endpoint on the network the page runs on — so prefer one of the server patterns that follow for anything a user runs.
+The published face is core, so the same `createOllama` call runs unchanged in a browser module. Point `url` at whatever the page can actually reach: the daemon's own origin where it answers that origin, or your own server standing in front of it. A page that reaches a daemon directly is a development arrangement — it puts the model endpoint on the network the page runs on — so prefer one of the server patterns that follow for anything a user runs. The daemon decides the page's origin before the call: a browser sends an `OPTIONS` preflight to `/api/chat` first, and a daemon that does not permit that origin refuses it, so set `OLLAMA_ORIGINS` to include the origin the page is served from. [`tests/service/page.test.ts`](../tests/service/page.test.ts) drives this arrangement for real, and gates it behind that same preflight.
 
 ```ts
 import { createOllama } from '@orkestrel/ollama'
@@ -259,7 +259,7 @@ const relayed = await browser.generate(messages, abort.signal)
 relayed.content // the daemon's answer, reassembled from the relay's frames
 ```
 
-A refusal never becomes a frame: a wrong credential reaches the browser as a `ProviderError` with code `'HTTP'` and status `401`, and the provider on the server is never entered. [`agent.md`](agent.md) states the frame vocabulary, the byte limit, and the rest of the refusal statuses. A page calling the relay from another origin needs CORS permission headers the relay route does not send, so serve the page from the relay server's own origin (as the recorded Chrome 148 run did) or put an origin-checking, CORS-answering middleware in front of the route (see the server guide), naming the `OPTIONS` preflight the browser sends with `authorization` and `content-type` as the requested headers.
+A refusal never becomes a frame: a wrong credential reaches the browser as a `ProviderError` with code `'HTTP'` and status `401`, and the provider on the server is never entered. [`agent.md`](agent.md) states the frame vocabulary, the byte limit, and the rest of the refusal statuses. A page calling the relay from another origin needs CORS permission headers the relay route does not send, so serve the page from the relay server's own origin (which is what [`tests/service/page.test.ts`](../tests/service/page.test.ts) does, from one loopback fixture serving the page, its modules, and the route) or put an origin-checking, CORS-answering middleware in front of the route (see the server guide), naming the `OPTIONS` preflight the browser sends with `authorization` and `content-type` as the requested headers.
 
 ### Routing through your own server (obfuscated tokens)
 
@@ -348,16 +348,16 @@ A cancel is outside that taxonomy: the caller's signal and the deadline both thr
 
 ## Tests
 
-The hermetic projects — `src:core`, `setup`, `guides`, `conformance`, `policy`, and `config` — run with no daemon and no network. The `service` project requires a warm local Ollama, and `distribution` packs and installs the artifact.
+The hermetic projects — `src:core`, `setup`, `guides`, `conformance`, `policy`, and `config` — run with no daemon and no network. The `service` project requires a warm local Ollama and, for the page proof, a Chromium-family browser and a built `dist`; `distribution` packs and installs the artifact.
 
 - [`tests/guides.test.ts`](../tests/guides.test.ts) — the `## Surface` ↔ `src/core` bijection (value + type exports), the `OllamaProvider` method bijection, and the equality gate: every `Summary` cell against its declaration's description paragraph, the titled `createOllama + generate` fence against the `@example` block of that title (pinned so the titled pair cannot be retired silently), and the README pitch against this guide's tagline. It also runs the flagship fences and asserts the values their comments claim.
 - [`tests/src/core/OllamaProvider.test.ts`](../tests/src/core/OllamaProvider.test.ts) — hermetic provider request-shape, framing, transport-seam, abort, deadline, and unreachable-upstream coverage, plus the streaming fold — deltas, tool-call accumulation, done-line usage, the unterminated tail flush, and think separation — driven over a canned NDJSON transport. Its recording proxy uses a deliberately unreachable default and asserts only captured requests and local provider behavior.
 - [`tests/src/core/helpers.test.ts`](../tests/src/core/helpers.test.ts) — the wire leaves: the request projection and every response extraction, including each malformed-wire degradation.
 - [`tests/src/core/factories.test.ts`](../tests/src/core/factories.test.ts) — hermetic `createOllama` shape, identity, defaults, passthrough, and unreachable-upstream coverage.
 - [`tests/src/core/integration.test.ts`](../tests/src/core/integration.test.ts) — the `src/core` integration scope. A real `@orkestrel/server` + `@orkestrel/router` relay in front of this provider carries ordered content and thinking deltas, tools, and usage while keeping the browser and daemon credentials apart, refuses a wrong bearer with an empty `401` before the daemon transport is entered, crosses a browser cancel and a server deadline as an abort frame with its partial, reduces a daemon stream failure to the fixed public error frame, and replays a returned tool call. Beside those, hermetic context framing, recap, reference, cherry-pick, canonical assembly order, scope allow-lists, workspace injection, and conversation selection run through the unreachable recording proxy, with a compile-time drift gate asserting the wire request and response shapes stay compatible with the official `ollama` client's types; that gate's authoritative check is `npm run check` (root tsc), while its run under vitest is an incidental no-op (`expectTypeOf` performs no runtime assertions).
-- [`tests/setup.test.ts`](../tests/setup.test.ts) — the shared host-independent test infrastructure, over the conversation padding, the throwing and recording summarizers, and the workspace seeder `tests/setup.ts` exports, and over the host-independent half of `tests/setupServer.ts`: its request-narrowing guards, its refusing and streaming transports, its tool fixtures, its scripted agent stream and agent-stream driver, and its environment readers.
-- [`tests/setupServer.test.ts`](../tests/setupServer.test.ts) — the Node-resource half of `tests/setupServer.ts`: the recording proxy and the relay server on real loopback sockets, the captured and open transports, whose fixtures answer in memory, the capture wait, the provider-stream driver, and the shared wire tables `WEATHER_TOOL` and the insatiable tool's chunk line.
-- [`tests/setupService.test.ts`](../tests/setupService.test.ts) — the hermetic half of the `service` project's setup: the environment readers, the sampling tables, and the readiness contract.
+- [`tests/setup.test.ts`](../tests/setup.test.ts) — the shared host-independent test infrastructure, over the conversation padding, the throwing and recording summarizers, the workspace seeder, and the `PAGE_TOOL` definition `tests/setup.ts` exports, and over the host-independent half of `tests/setupServer.ts`: its request-narrowing guards, its refusing and streaming transports, its tool fixtures, its scripted agent stream and agent-stream driver, and its environment readers.
+- [`tests/setupServer.test.ts`](../tests/setupServer.test.ts) — the Node-resource half of `tests/setupServer.ts`: the recording proxy and the relay server on real loopback sockets, the captured and open transports, whose fixtures answer in memory, the capture wait, the provider-stream driver, the wire tables `WEATHER_TOOL` and the insatiable tool's chunk line, and the page fixture's Node half — the request recorder the relay server and the page fixture share, the derived import map, the served document's presence guards, the contained file route, the control route, the port reservation, the membership the page bounds declare — the attempt allowance, the release share beside it, the per-call shares spent inside them, the case bound that contains the pair, and the launch count the retry spends — the ordering the live controls' own intervals hold, the attempt deadline's own expiry error, the elapsed completion a bounded attempt reports on each interleaving that can outlast it (an acquisition that never settles, one that settles inside the release share, a release that parks past that share, and a release that crossed the allowance), each of those measured against the deadlines it had to wait out plus one named scheduling allowance, so what the case proves is timer-bounded completion rather than a nominal sum, the failure each of them keeps reachable as its cause — the attempt's own failure under a composed strand, and the deadline's `TimeoutError` under a crossed release — the reading each thrown failure carries into a composed message, the decision the bounded retry's predicate makes over an inert attempt record, including the interrupted run it refuses, the release order a real fixture takes when the release after it rejects, the evaluate boundary's narrowing and the deadline it carries, and the guards that narrow what the page reports back.
+- [`tests/setupService.test.ts`](../tests/setupService.test.ts) — the hermetic half of the `service` project's setup: the environment readers, the sampling tables, the readiness contract, and each live page gate's refusal — a host with no browser, a tree with no build, and a daemon that refuses the page's origin.
 - [`tests/conformance.test.ts`](../tests/conformance.test.ts) — where this package's wire types drift from the official `ollama` client they are written against.
 - [`tests/distribution.test.ts`](../tests/distribution.test.ts) — the packed package installed into a throwaway consumer: the exports map, the shipped declarations, and the module objects a real runtime hands that consumer.
 - [`tests/policy.test.ts`](../tests/policy.test.ts) and [`tests/config.test.ts`](../tests/config.test.ts) — the vendored cross-cutting proofs: the path- and text-shaped repository laws, and that the root configuration resolves its aliases, projects, and outputs.
@@ -365,6 +365,7 @@ The hermetic projects — `src:core`, `setup`, `guides`, `conformance`, `policy`
 - [`tests/service/factories.test.ts`](../tests/service/factories.test.ts) — live `createOllama` generation and streaming coverage.
 - [`tests/service/relay.test.ts`](../tests/service/relay.test.ts) — the browser-to-server relay against the live daemon: a generated answer through the authenticated route, streamed deltas joining to the settled content, and a cancel after a live delta returning the relay's partial.
 - [`tests/service/transport.test.ts`](../tests/service/transport.test.ts) — the transparent wire proxy, end-to-end. A `createRecordingProxy(OLLAMA_CONFIG.host)` — a real `@orkestrel/server` + `@orkestrel/router` HTTP server — records the inbound request, forwards it to the selected Ollama service, and streams the response back.
+- [`tests/service/page.test.ts`](../tests/service/page.test.ts) — the live page receipt, in a real Chrome or Edge that `@orkestrel/browser` launches against a `127.0.0.1` fixture serving the page, the installed `@orkestrel` module tree, this workspace's own build, a `/control` route, and the authenticated relay from one origin. It proves that the published closure evaluates in the page with the page error recorder and the console recorder quiet, that the page parks exactly the operation table this proof evaluates by name, read back out of the running browser, that an `Agent` holding a page-defined DOM-writing `Tool` completes a tool loop against the live daemon over the same-origin relay and carries the minted receipt into the next turn's `role: 'tool'` message on the relay wire and the daemon wire, that the browser log, the page's Resource Timing drain, and the fixture's own record each report a request the page deliberately made, and the page error recorder and the console recorder each report a fault the page deliberately produced, that a wrong bearer is refused before the daemon is contacted, and that `createOllama` in the page answers a prompt on the daemon's own origin. Controls beside those drive a real browser through each interleaving the attempt bound covers, and assert the elapsed time of the whole call against the allowance plus the release share every time: an allowance too short to finish reads the attempt's own expiry error back rather than an inner browser timeout; an allowance the observation outlasts leaves the session released; an acquisition that settles after the allowance is released rather than abandoned, and is never reported as stranded; and an attempt whose release crossed the allowance reports that release rather than the answer the observation had already returned. Every precondition is a hard throw naming its fix — the daemon and model from `tests/setupService.ts`, the browser from `requirePageBrowser`, the build from `requireBuild`, and the daemon's permission for the page origin from `requireDaemonOrigin` — so a host missing one fails the project rather than skipping.
 - [`tests/service/tools.test.ts`](../tests/service/tools.test.ts) and [`tests/service/authority.test.ts`](../tests/service/authority.test.ts) — live tool dispatch through the agent loop, and the authority gate's approval and denial paths.
 - [`tests/service/budget.test.ts`](../tests/service/budget.test.ts) and [`tests/service/lifecycle.test.ts`](../tests/service/lifecycle.test.ts) — live token-budget enforcement mid-stream, and the agent's status, event, and abort lifecycle.
 - [`tests/service/schema.test.ts`](../tests/service/schema.test.ts) and [`tests/service/scopes.test.ts`](../tests/service/scopes.test.ts) — a live structured-output `schema` constraining the answer, and a live scope filtering what reaches the wire.

package/dist/host/guides/tool.md

@@ -11,10 +11,11 @@ call whose shape is data, so whoever calls it can discover it, present it, and i
 knowing anything about the code behind it.
 
 `Tool` and `ToolManager` carry the runtime. A `Tool` is inert — a definition plus a handler, with
-no lifecycle and no failure handling of its own. A `ToolManager` is the live surface a caller
-holds: it hands `definitions()` outward, takes a `ToolCall` back, and answers with a `ToolResult`,
-a result rather than a throw for a call whose members are plain values. Tools stay in the map by
-name in insertion order. Everything else in this module is the plain data those two exchange.
+no lifecycle. A configured contract validates arguments before its handler runs. A `ToolManager`
+is the live surface a caller holds: it hands `definitions()` outward, takes a `ToolCall` back, and
+answers with a `ToolResult`, a result rather than a throw for a call whose members are plain
+values. Tools stay in the map by name in insertion order. Everything else in this module is the
+plain data those two exchange.
 
 **Anyone can call a tool.** Nothing here is model-specific — `tools.execute(call)` is an ordinary
 async call returning an ordinary result, and plain application code may drive it directly. The
@@ -24,8 +25,9 @@ capability to a remote client, a backend dispatching a named operation. `@orkest
 `@orkestrel/mcp` are two such callers; ready-made tools ship in `@orkestrel/toolbox`.
 
 **Mechanism only.** This runtime advertises, dispatches, and contains failure. It transports
-nothing, validates no arguments against a tool's schema, authorizes no call, and ships no concrete
-tools. Optional caller context is consumer-asserted and forwarded without verification. Each trust
+nothing, authorizes no call, and ships no concrete tools. A `contract` derives the advertised
+parameter schema and validates arguments; `parameters` alone remains descriptive. Caller identity
+in the execution context is consumer-asserted and forwarded without verification. Each trust
 decision belongs to the invoking consumer, to a policy layer, or to the tool itself. Progress
 reporting belongs there too: it is a property of the invoking consumer's execution context, one
 layer up — the `@orkestrel/mcp` package's execution context carries a progress reporter — never of
@@ -35,7 +37,7 @@ Source: [`src/core`](../src/core). Published through `@orkestrel/tool`.
 
 ## Surface
 
-### Contracts
+### Types
 
 The data shapes, from [`types.ts`](../src/core/types.ts). Every property is readonly, and an
 optional field the caller did not supply is absent from the value. A `Shape` cell holds an
@@ -43,26 +45,34 @@ interface's data members as bare names in braces, `?` marking an optional member
 introducing its call-signature members, and a type alias's own type literal with a union's arms
 escaped as `\|`. An extended interface's name comes before `plus`, with the members it adds after.
 
-| Name                   | Kind      | Shape                                                                  | Summary                                                                          |
-| ---------------------- | --------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
-| `ToolDefinition`       | interface | `{ name, description?, parameters? }`                                  | Describes a tool as advertised to a caller.                                      |
-| `ToolCall`             | interface | `{ id, name, arguments, caller? }`                                     | Describes one request to run a named tool.                                       |
-| `ToolSuccess`          | interface | `Success<unknown> plus { id, name }`                                   | Reports the successful outcome of executing a `ToolCall`.                        |
-| `ToolFailure`          | interface | `Failure<string> plus { id, name }`                                    | Reports the failed outcome of executing a `ToolCall`.                            |
-| `ToolOptions`          | interface | `{ name, description?, summary?, parameters?, execute }`               | Configures an executable tool.                                                   |
-| `ToolInterface`        | interface | `ToolDefinition plus { summary? } plus execute`                        | Represents an executable tool: its advertised definition plus its local handler. |
-| `ToolManagerInterface` | interface | `{ count } plus add, tool, tools, definitions, execute, remove, clear` | Represents a registry of executable tools with per-call error isolation.         |
-| `ToolResult`           | type      | `ToolSuccess \| ToolFailure`                                           | Represents the outcome of executing a `ToolCall`.                                |
+| Name                   | Kind      | Shape                                                                                                                                                           | Summary                                                                          |
+| ---------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `ToolDefinition`       | interface | `{ name, title?, description?, parameters?, annotations? }`                                                                                                     | Describes a tool as advertised to a caller.                                      |
+| `ToolCall`             | interface | `{ id, name, arguments }`                                                                                                                                       | Describes one request to run a named tool.                                       |
+| `ToolSuccess`          | interface | `Success<unknown> plus { id, name }`                                                                                                                            | Reports the successful outcome of executing a `ToolCall`.                        |
+| `ToolFailure`          | interface | `Failure<string> plus { id, name }`                                                                                                                             | Reports the failed outcome of executing a `ToolCall`.                            |
+| `ToolOptions`          | interface | `{ name, title?, description?, summary?, parameters?, contract?, annotations?, execute }`                                                                       | Configures an executable tool.                                                   |
+| `ToolInterface`        | interface | `ToolDefinition plus { summary? } plus execute`                                                                                                                 | Represents an executable tool: its advertised definition plus its local handler. |
+| `ToolManagerInterface` | interface | `{ count, emitter } plus add, tool, tools, definitions, execute, remove, clear, destroy`                                                                        | Represents a registry of executable tools with per-call error isolation.         |
+| `ToolManagerEventMap`  | type      | `{ readonly add: readonly [tool: ToolInterface]; readonly remove: readonly [tool: ToolInterface]; readonly clear: readonly [tools: readonly ToolInterface[]] }` | Names the events a tool registry publishes.                                      |
+| `ToolManagerOptions`   | interface | `{ on?, error? }`                                                                                                                                               | Configures a tool registry's initial listeners and error handling.               |
+| `ToolResult`           | type      | `ToolSuccess \| ToolFailure`                                                                                                                                    | Represents the outcome of executing a `ToolCall`.                                |
+| `ToolContext`          | interface | `{ signal, caller? }`                                                                                                                                           | Carries the signal and consumer-asserted identity for an execution.              |
+| `ToolAnnotations`      | interface | `{ pure?, untrusted?, consequential? }`                                                                                                                         | Describes the observable effects and content of a tool.                          |
+| `ToolErrorCode`        | type      | `'SCHEMA' \| 'ARGUMENTS'`                                                                                                                                       | Identifies a schema conflict or an argument validation failure.                  |
+| `ToolErrorContext`     | interface | `{ faults? }`                                                                                                                                                   | Carries the structured faults behind an argument validation failure.             |
 
 `ToolInterface` and `ToolManagerInterface` list every member they declare or inherit. The
 call-signature members of each are documented under [Methods](#methods); the readonly `count` of
 `ToolManagerInterface` reports how many tools are registered and is a Surface member with no
-method row.
+method row. Its readonly `emitter` publishes `add`, `remove`, and `clear` with the payloads
+declared by `ToolManagerEventMap`. The `ToolManagerOptions` fields supply initial `on` hooks
+and an `error` handler for listener throws.
 
 ### Validators
 
-The call-envelope guard, from [`validators.ts`](../src/core/validators.ts). In a guard table a
-`Shape` cell holds the type the guard narrows to.
+The call-envelope guard, from [`validators.ts`](../src/core/validators.ts). In a guard
+table a `Shape` cell holds the type the guard narrows to.
 
 | Name         | Kind     | Shape      | Summary                                                                                                              |
 | ------------ | -------- | ---------- | -------------------------------------------------------------------------------------------------------------------- |
@@ -72,19 +82,19 @@ The call-envelope guard, from [`validators.ts`](../src/core/validators.ts). In a
 
 The advertised-definition projection, from [`helpers.ts`](../src/core/helpers.ts).
 
-| Name               | Kind     | Signature                                 | Summary                                                                                                                                                                              |
-| ------------------ | -------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `toolToDefinition` | function | `(tool: ToolInterface) => ToolDefinition` | Projects a tool onto the plain definition advertised to a caller, advertising an authored `summary` in place of the full description and carrying the parameter schema by reference. |
+| Name               | Kind     | Signature                                 | Summary                                                                                                                                                                                        |
+| ------------------ | -------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `toolToDefinition` | function | `(tool: ToolInterface) => ToolDefinition` | Projects a tool onto the plain definition advertised to a caller, advertising an authored `summary` in place of the full description and carrying `parameters` and `annotations` by reference. |
 
 ### Factories
 
 From [`factories.ts`](../src/core/factories.ts) — the constructor-free way to reach `Tool` and
 `ToolManager`.
 
-| Name                | Kind     | Signature                                 | Summary                                                                                                                                                                                                                    |
-| ------------------- | -------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `createTool`        | function | `(options: ToolOptions) => ToolInterface` | Creates an executable tool bound to the supplied handler, returned as a `ToolInterface` so a call site holds the published contract rather than the `Tool` class.                                                          |
-| `createToolManager` | function | `() => ToolManagerInterface`              | Creates an empty registry that advertises definitions and executes calls with per-call error isolation, returned as a `ToolManagerInterface` so a caller holds the published contract rather than the `ToolManager` class. |
+| Name                | Kind     | Signature                                                | Summary                                                                                                                                                                                                                    |
+| ------------------- | -------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `createTool`        | function | `(options: ToolOptions) => ToolInterface`                | Creates an executable tool bound to the supplied handler, returned as a `ToolInterface` so a call site holds the published contract rather than the `Tool` class.                                                          |
+| `createToolManager` | function | `(options?: ToolManagerOptions) => ToolManagerInterface` | Creates an empty registry that advertises definitions and executes calls with per-call error isolation, returned as a `ToolManagerInterface` so a caller holds the published contract rather than the `ToolManager` class. |
 
 ### Classes
 
@@ -92,51 +102,67 @@ The implementing classes, from [`Tool.ts`](../src/core/tools/Tool.ts) and
 [`ToolManager.ts`](../src/core/tools/ToolManager.ts) — each documented in full under its own
 heading following this table.
 
-| Name          | Kind  | Summary                                                                      |
-| ------------- | ----- | ---------------------------------------------------------------------------- |
-| `Tool`        | class | Binds an executable tool definition to a handler.                            |
-| `ToolManager` | class | Represents an insertion-ordered tool registry with per-call error isolation. |
+| Name          | Kind  | Summary                                                                                |
+| ------------- | ----- | -------------------------------------------------------------------------------------- |
+| `Tool`        | class | Binds an executable tool definition to a handler.                                      |
+| `ToolManager` | class | Represents an insertion-ordered tool registry with per-call error isolation.           |
+| `ToolError`   | class | Reports a schema conflict or argument validation failure with a machine-readable code. |
 
 ### `Tool`
 
 The implementing class of `ToolInterface`, from [`Tool.ts`](../src/core/tools/Tool.ts). It
 copies the fields it was given — omitting each optional one that was not supplied — and keeps
 the handler in a private field, so a tool's advertised shape cannot drift from what it executes.
-The parameter schema, argument record, and present caller context are forwarded by reference,
-never cloned. `Tool` deliberately does not catch: a handler that throws throws, and per-call
-isolation belongs to the registry that dispatched it. See [`## Methods`](#methods) for its public
-call surface.
+An explicit parameter schema and the execution context are forwarded by reference. Without a
+contract, the argument record retains its identity too. A contract compiles at construction and
+derives the parameter schema through the contract package's projection. The compiled contract
+checks arguments before handler entry and supplies its parsed copy to the handler.
+`Tool` deliberately does not catch: a handler that throws throws, and per-call isolation belongs
+to the registry that dispatched it. See [`## Methods`](#methods) for its public call surface.
 
 ### `ToolManager`
 
 The implementing class of `ToolManagerInterface`, from
-[`ToolManager.ts`](../src/core/tools/ToolManager.ts). One name-keyed map is its whole state:
-tools stay in insertion order, `tools()` and `definitions()` return fresh readonly arrays rather
+[`ToolManager.ts`](../src/core/tools/ToolManager.ts). It stores tools in a name-keyed map and owns
+an emitter for registry changes. Tools stay in insertion order, `tools()` and `definitions()` return fresh readonly arrays rather
 than a view of that map, and every projection is computed on demand so a mutation can never
 leave a stale copy behind. It is the only place a call can fail into a result instead of an
 exception. See [`## Methods`](#methods) for its public call surface.
 
+### `ToolError`
+
+The error class from [`errors.ts`](../src/core/errors.ts) extends `Error`. Its constructor takes
+`code`, `message`, and optional `context`. Direct tool execution throws an `ARGUMENTS` error with
+the full fault report in `context.faults`; the manager contains it as a message. Use `isToolError`
+to narrow a caught value. See [Contract validation and errors](#contract-validation-and-errors)
+for an executed example.
+
+| Name          | Kind     | Shape       | Summary                                                                      |
+| ------------- | -------- | ----------- | ---------------------------------------------------------------------------- |
+| `isToolError` | function | `ToolError` | Checks whether a value is a tool error, containing hostile prototype access. |
+
 ## Methods
 
 The public call-signature members of each behavioral interface, one table per interface.
 
 #### `ToolInterface`
 
-| Method    | Returns                       | Summary                                                                                              |
-| --------- | ----------------------------- | ---------------------------------------------------------------------------------------------------- |
-| `execute` | `Promise<unknown> \| unknown` | Runs the tool's handler with the caller-supplied arguments and any consumer-asserted caller context. |
+| Method    | Returns                       | Summary                                                                           |
+| --------- | ----------------------------- | --------------------------------------------------------------------------------- |
+| `execute` | `Promise<unknown> \| unknown` | Runs the tool's handler with the caller-supplied arguments and execution context. |
 
 #### `ToolManagerInterface`
 
-| Method        | Returns                                        | Summary                                        |
-| ------------- | ---------------------------------------------- | ---------------------------------------------- |
-| `add`         | `void`                                         | Registers one tool.                            |
-| `tool`        | `ToolInterface \| undefined`                   | Finds one registered tool by name.             |
-| `tools`       | `readonly ToolInterface[]`                     | Lists the registered tools in insertion order. |
-| `definitions` | `readonly ToolDefinition[]`                    | Lists the definitions advertised to a caller.  |
-| `execute`     | `Promise<ToolResult \| readonly ToolResult[]>` | Executes one call with error isolation.        |
-| `remove`      | `boolean`                                      | Removes one registered tool.                   |
-| `clear`       | `void`                                         | Removes every registered tool.                 |
+| Method        | Returns                                        | Summary                                                  |
+| ------------- | ---------------------------------------------- | -------------------------------------------------------- |
+| `add`         | `void`                                         | Registers one tool.                                      |
+| `tool`        | `ToolInterface \| undefined`                   | Finds one registered tool by name.                       |
+| `tools`       | `readonly ToolInterface[]`                     | Lists the registered tools in insertion order.           |
+| `definitions` | `readonly ToolDefinition[]`                    | Lists the definitions advertised to a caller.            |
+| `execute`     | `Promise<ToolResult \| readonly ToolResult[]>` | Executes one call with error isolation.                  |
+| `remove`      | `boolean`                                      | Removes one registered tool.                             |
+| `clear`       | `void`                                         | Removes every registered tool.                           |
+| `destroy`     | `void`                                         | Removes every tool and releases the emitter's listeners. |
 
 `add`, `execute`, and `remove` each take one value or a readonly batch of them. A batch `add`
 registers every tool, later entries winning over earlier ones with the same name; a batch
@@ -170,15 +196,16 @@ const add = createTool({
 `new Tool({ … })` builds the same thing; reach for `createTool` where a call site must not name
 a class.
 
-The schema is descriptive runtime data, forwarded by reference and never interpreted here. A
-handler always receives the open `Readonly<Record<string, unknown>>` the caller sent and narrows
-the fields it consumes — declaring `required` tells the caller what to send, not this runtime
-what to reject. Its optional second parameter is the call's `caller` value verbatim. That value
-is asserted by the invoking consumer and is never verified here; a handler or policy layer must
-make every authorization and trust decision. Handlers may be synchronous or asynchronous; the
-registry awaits either. A handler can declare no parameter, one, or two. When the call carries
-no caller context the registry invokes the handler with the arguments record alone, so a handler
-that reads its own arity sees one argument and a handler that declares `caller` sees `undefined`.
+An explicit `parameters` schema is descriptive runtime data, forwarded by reference. Declaring
+`required` in that schema tells the caller what to send; it does not validate the payload. Use the
+`contract` option when the runtime must validate arguments.
+
+A handler receives a `Readonly<Record<string, unknown>>` and a required `ToolContext`.
+Without a contract, that record is the original input; with a contract, it is the parsed value.
+The context holds an `AbortSignal` and optional unverified caller identity. Handlers may omit
+unused parameters from their declaration. Every invocation still supplies the arguments and the
+context. A direct `tool.execute(args, context)` call must provide the context; the manager creates
+one when its caller omits it. Handlers may return synchronously or asynchronously.
 
 When one was authored, `definitions()` projects the tool's `summary` as `description`, advertising
 it in place of the full description. The full text stays on the tool for direct lookup through
@@ -214,10 +241,10 @@ moving it — the sequence a caller sees stays stable while a tool behind a name
 Remove a name and add it again and it lands at the end, because the name is genuinely new to the
 map. In a batch, later entries win over earlier ones with the same name.
 
-`definitions()` projects fresh plain objects on every call: `name`, then `description` only when
-a summary or description exists, then `parameters` only when a schema exists, with the schema
-object's original identity preserved. Nothing that arrives on a definition is a live handle on
-the registry — advertising cannot be used to reach the handlers.
+`definitions()` projects fresh plain objects on every call: `name`, followed by present `title`,
+`description`, `parameters`, and `annotations` fields. A summary replaces the advertised
+description. The schema and annotations retain their original identities. Nothing that arrives on
+a definition is a live handle on the registry — advertising cannot be used to reach the handlers.
 
 ## Calls and results
 
@@ -227,11 +254,12 @@ it, then execute:
 ```ts
 import { isToolCall } from '@orkestrel/tool'
 
+tools.add(add) // restores the tool removed by the registry example
+
 const incoming: unknown = {
 	id: 'call-1',
 	name: 'add',
 	arguments: { left: 2, right: 3 },
-	caller: { subject: 'user-42' },
 }
 
 if (isToolCall(incoming)) {
@@ -250,13 +278,12 @@ const batch = await tools.execute([
 ```
 
 `isToolCall` validates the envelope only: the `id`, the `name`, and that `arguments` is a plain
-record. Optional `caller` remains opaque `unknown`; the guard does not verify it. It never checks
-arguments against a tool's schema, so a well-formed call for a badly shaped payload still reaches
-the handler, which is exactly where the domain knowledge to reject it lives.
+record. The guard ignores extra fields without reading them. A call carries no execution context.
+The registered tool's contract, when configured, validates the arguments during execution.
 
-Caller context exists only on the call and in the tool execution chain. This package never adds
-it to advertised definitions, schemas, results, or logs. When present it is forwarded by
-identity; when absent it is not passed at all.
+Execution context travels as a separate argument. This package adds neither the signal nor caller
+identity to definitions, schemas, calls, or results. A handler can explicitly return a context
+member as its own value. The context and caller identity reach the handler unchanged.
 
 Execution always resolves for a call whose members are plain values; a call whose `id` or `name`
 accessor throws when read makes `execute` reject, because no correlated result can be built
@@ -270,7 +297,7 @@ carries `error`. Narrow on `success` to distinguish the two; a present success v
 necessarily meaningful or truthy.
 
 An in-process caller needing a typed error can call `tools.tool(name)`, then
-`tool.execute(args)` inside its own `try`/`catch`.
+`tool.execute(args, context)` inside its own `try`/`catch`.
 
 A batch is dispatched concurrently and answered in input order, with each call whose members are
 plain values isolated from its siblings — a handler failure never voids the batch, a call whose
@@ -278,6 +305,174 @@ plain values isolated from its siblings — a handler failure never voids the ba
 calls rather than collapsing into one. That isolation is what lets a caller feed every result back
 to whatever produced the calls and let it react to the failures itself.
 
+The sections that follow are independent examples.
+
+## Execution context
+
+For versions from 0.0.15, `caller` lives on `ToolContext` instead of `ToolCall`. A handler whose
+second parameter is annotated `unknown` still compiles and receives the context object rather
+than the caller value. Update such a handler to read `context.caller`.
+
+Pass a context when the caller owns cancellation or carries an asserted identity:
+
+```ts
+import type { ToolContext } from '@orkestrel/tool'
+import { createTool, createToolManager } from '@orkestrel/tool'
+
+const controller = new AbortController()
+const context: ToolContext = { signal: controller.signal, caller: { subject: 'reader' } }
+const tools = createToolManager()
+tools.add(createTool({ name: 'signal', execute: (_args, execution) => execution.signal.aborted }))
+const call = { id: 'signal-1', name: 'signal', arguments: {} }
+const result = await tools.execute(call, context)
+result // { id: 'signal-1', name: 'signal', success: true, value: false }
+controller.abort('request ended')
+const aborted = await tools.execute(call, context)
+aborted // { id: 'signal-1', name: 'signal', success: false, error: 'request ended' }
+```
+
+The manager creates a non-aborted signal for each execution that omits a context. A batch shares
+one context, whether supplied or created. Before entering each registered handler, the manager
+checks the signal. A batch dispatches every call in one synchronous pass, so an abort raised after
+dispatch reaches only handlers that observe the signal. A synchronous abort inside the dispatch
+pass prevents later handler entry. An already-aborted signal produces a failure with
+`String(signal.reason)`, or `aborted` if the reason is `undefined`. An unknown tool still produces
+its not-found failure.
+After handler entry, the handler must observe the signal and stop its own work. The manager awaits
+that handler and contains its throws as usual; an abort does not force a running handler to settle.
+
+## Contract validation and errors
+
+A contract compiles at construction. Its schema projects to `parameters` through
+`schemaToParameters(createContract(shape).schema)` from `@orkestrel/contract`; an undefined
+projection leaves parameters absent. Supplying `contract` and `parameters` together throws a
+`ToolError` with code `SCHEMA`.
+
+The contract's `explain` method reports parse faults before the handler runs. It accepts coercible
+values, such as a numeric string for a number. After a clean report, `Tool.execute` forwards
+`contract.parse(args)`: the owned, normalized copy in the schema's types, with undeclared keys
+dropped. A handler cannot rely on undeclared input keys being present. Without a contract, the
+raw argument record is forwarded unchanged. A parse fault throws `ToolError` with code
+`ARGUMENTS`. The message names the first fault's path and reason, then its expected and received
+values when the fault carries them; a constraint fault also names its constraint and limit when
+present. Array paths join with `.`; string paths stay unchanged. A root array path is empty, so
+its message starts with `: `. The error's `context.faults` holds the full report. A `variant` fault
+carries `variants`, appended as `; variants <n>`; a `oneOf` fault carries `matched`, appended as
+`; matched <n>`. A missing field carries expected alone. Contract construction errors from the
+dependency propagate unchanged. If parsing returns a value that isn't a record after a clean
+explanation, execution throws `ToolError` with code `ARGUMENTS` and message
+`Arguments did not parse`, without `context`, before handler entry.
+
+Use the guard to narrow an error at the direct execution boundary:
+
+```ts
+import type { ToolErrorCode, ToolErrorContext } from '@orkestrel/tool'
+import { numberShape, objectShape } from '@orkestrel/contract'
+import { ToolError, createTool, isToolError } from '@orkestrel/tool'
+
+const tool = createTool({
+	name: 'amount',
+	contract: objectShape({ amount: numberShape() }),
+	execute: (args) => args.amount,
+})
+const context = { signal: new AbortController().signal }
+tool.execute({ amount: 3 }, context) // 3
+try {
+	tool.execute({ amount: 'invalid' }, context)
+} catch (error) {
+	if (!isToolError(error)) throw error
+	const code: ToolErrorCode = error.code
+	code // 'ARGUMENTS'
+	const details: ToolErrorContext | undefined = error.context
+	details?.faults?.[0]?.reason // 'type'
+	error.message // 'amount: type; expected number; received "invalid"'
+}
+const conflict = new ToolError('SCHEMA', 'Choose contract or parameters')
+conflict.code // 'SCHEMA'
+isToolError(conflict) // true
+isToolError(new Error('Unrelated')) // false
+```
+
+The manager contains this same argument refusal as a `ToolFailure`; it carries the message rather
+than the error instance or fault report. `ToolError` extends `Error`, exposes its readonly `code`
+and optional readonly `context`, and inherits the standard error methods.
+
+## Advertising title and annotations
+
+A title supplies display text. Annotations describe observable effects and content: `pure` reports
+no state changes the caller can observe, `untrusted` reports that the result can carry content the
+tool did not author, and `consequential` reports an effect the caller must confirm. These are
+claims by the tool author; this runtime neither verifies them nor enforces confirmation.
+
+Project the advertising fields while keeping the detailed description on the tool:
+
+```ts
+import type { ToolAnnotations } from '@orkestrel/tool'
+import { createTool, toolToDefinition } from '@orkestrel/tool'
+
+const annotations: ToolAnnotations = { pure: true, untrusted: false, consequential: false }
+const tool = createTool({
+	name: 'echo',
+	title: 'Echo',
+	description: 'Return the supplied value unchanged.',
+	summary: 'Echo a value.',
+	annotations,
+	execute: (args) => args.value,
+})
+const definition = toolToDefinition(tool)
+definition.title // 'Echo'
+definition.description // 'Echo a value.'
+definition.annotations === annotations // true
+```
+
+## Patterns
+
+### Observe registry changes
+
+Subscribe through the `on` option or `tools.emitter.on`. Each event describes the registry at the
+moment it is published. A listener that mutates the registry re-enters synchronously; its own
+events publish before the outer call resumes.
+
+An addition publishes `add` with the map holding that exact tool. A replacement keeps its
+registration position and publishes `remove` with the previous instance while the replacement
+is already installed. A listener must not read absence from the map to confirm that removal.
+After the removal listeners return, `add` publishes only if the map still holds that exact
+replacement. Removing a present name publishes `remove` after deletion; a missing name publishes
+nothing. Batches apply their operations in argument order.
+Each `clear` call publishes one `clear` with the removed tools in registration order, including
+an empty array when the registry was empty. Execution publishes no registry events.
+
+Collect event names while registering, replacing, removing, and clearing a tool:
+
+```ts
+import { createTool, createToolManager } from '@orkestrel/tool'
+
+const events: string[] = []
+const tools = createToolManager({
+	on: {
+		add: () => events.push('add'),
+		remove: () => events.push('remove'),
+		clear: () => events.push('clear'),
+	},
+})
+tools.add(createTool({ name: 'echo', execute: (args) => args.value }))
+tools.add(createTool({ name: 'echo', execute: () => 'replacement' }))
+tools.remove('echo')
+tools.clear()
+events // ['add', 'remove', 'add', 'remove', 'clear']
+tools.destroy()
+tools.emitter.destroyed // true
+```
+
+Listeners run synchronously. A listener throw reaches the optional `error` handler as
+`(error, event)` and does not prevent sibling listeners. Without an error handler, the emitter
+swallows listener throws. Destruction clears the registry while listeners remain attached,
+destroys the emitter, then empties the map again without publishing. It returns with an empty
+registry even if a `clear` listener added a tool. An emission already underway delivers to its
+remaining snapshotted listeners, even when a listener destroys the registry before its siblings
+run. A destroyed registry publishes nothing; later additions still update its tool map, and
+later subscriptions do nothing.
+
 ## Callers
 
 The registry's two-sided shape — `definitions()` out, `execute()` back — is all a caller needs,
@@ -297,12 +492,13 @@ registers here unchanged.
 
 ## Tests
 
-- [`guides.test.ts`](../tests/guides.test.ts) — the `## Surface` ↔ `src/core` bijection, the `ToolInterface` ↔ `Tool` and `ToolManagerInterface` ↔ `ToolManager` method bijections, and the equality gate: every `Summary` cell against its declaration's description paragraph, the titled `Anatomy of a tool` fence against the `@example` block of that title (pinned so the titled pair cannot be retired silently), and the README pitch against this guide's tagline. It also runs the flagship fences and asserts the values their comments claim.
-- [`Tool.test.ts`](../tests/src/core/tools/Tool.test.ts) — definition binding, optional-field omission, argument identity, return values, and the deliberate absence of handler isolation.
-- [`ToolManager.test.ts`](../tests/src/core/tools/ToolManager.test.ts) — insertion order, overwrite and removal lifecycle, definition projection, and isolated single and batch execution.
-- [`factories.test.ts`](../tests/src/core/factories.test.ts) — factory construction and working instances.
-- [`helpers.test.ts`](../tests/src/core/helpers.test.ts) — definition projection: summary preference, omitted optional keys, projected key order, schema identity, and a fresh object per call.
+- [`guides.test.ts`](../tests/guides.test.ts) — the `## Surface` ↔ `src/core` bijection, the `ToolInterface` ↔ `Tool` and `ToolManagerInterface` ↔ `ToolManager` method bijections, and the equality gate: every `Summary` cell against its declaration's description paragraph, the titled `Anatomy of a tool` fence against the `@example` block of that title (pinned so the titled pair cannot be retired silently), and the README pitch against this guide's tagline. It also runs the flagship fences, including `Observe registry changes`, and asserts the values their comments claim against byte-equal transcriptions.
+- [`Tool.test.ts`](../tests/src/core/tools/Tool.test.ts) — definition binding, optional-field omission, argument and context identity, contract validation, error diagnostics, return values, and direct error propagation.
+- [`ToolManager.test.ts`](../tests/src/core/tools/ToolManager.test.ts) — insertion order, overwrite and removal lifecycle, definition projection, cancellation, context sharing, and isolated single and batch execution. Event proofs cover registration before `add`, ordered batch additions, the installed replacement during `remove`, `remove` before replacement `add`, synchronous replacement re-entry, a third instance a removal listener installs during a replacement, deletion before `remove`, silent missing names, ordered batch removals, populated and empty `clear` snapshots by identity, emitter destruction after clearing, an empty registry after teardown listeners re-add a tool, sibling delivery during mid-emission destruction, silent additions after destruction, and execution without registry events.
+- [`factories.test.ts`](../tests/src/core/factories.test.ts) — factory construction, working instances, initial registry hooks in publication order, sibling listener isolation, and listener-error forwarding.
+- [`helpers.test.ts`](../tests/src/core/helpers.test.ts) — definition projection: summary preference, omitted optional keys, projected key order, schema identity, title and annotations forwarding, and a fresh object per call.
 - [`validators.test.ts`](../tests/src/core/validators.test.ts) — tool-call envelope boundaries: incomplete calls, wrong field types, and non-record arguments.
+- [`errors.test.ts`](../tests/src/core/errors.test.ts) — `isToolError` recognition, unrelated-value rejection, and hostile prototype containment.
 
 ## See also