opentel-mcp 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,92 @@
 # Changelog
 
+## 0.13.0
+
+Closes the two open items from `docs/known-gaps.md` entry 10 (a
+raw-content audit of every attribute/span event this package emits) that
+needed a design decision before a fix — raw exception content on
+`recordException`/`setStatus`, and an unvalidated tool-result model field
+reaching `mcp.tool.model`/`gen_ai.response.model` — plus the two
+lower-risk fixes from the same entry that didn't need one. Full design:
+ADR 019 (`docs/adr/019-raw-content-on-spans.md`). See the README's new
+"What this library records" and "Error recording" sections for the
+operator-facing consequence of each.
+
+### Added — `errorRecording.mode` config (ADR 019 Part 1)
+
+- New top-level `errorRecording` option, sibling to `fingerprinting` /
+  `costTracking` / `thrashDetection` / `schemaDrift`: `'full'` (default,
+  byte-for-byte unchanged from every prior release —
+  `recordException(err)` + `setStatus({ message: err.message })` with the
+  raw error), `'normalized'` (reuses the existing
+  `normalizeMessage()`/`parseAndNormalizeStack()` fingerprinting pipeline
+  — no new scrubbing logic — to strip known-sensitive-shaped substrings
+  from the message and the local `cwd` prefix from the stack, without
+  mutating the original `err`, which both call sites still rethrow), or
+  `'none'` (records neither — the same `setStatus({ code: ERROR })`
+  no-message pattern already used for tool-level `isError: true`
+  failures). Applies to both thrown-exception paths, `tools/call` and
+  `tools/list`.
+- New `OTEL_MCP_ERROR_RECORDING_MODE` env var — same
+  option-then-env-then-default precedence, and the same silent fallback
+  to the default on an unrecognized value, as every other `OTEL_MCP_*`
+  config.
+- `error.type`/`exception.type` (both read from `err.name`) are now
+  capped at 128 characters unconditionally, in every mode — the same cap
+  `mcp.failure.error_class` uses below, reusing its exported constant
+  rather than a second, possibly-drifting copy.
+- Default stays `'full'` for all of `0.x`; ADR 019 Part 1 records the
+  intent to flip it to `'normalized'` at `1.0`, not before — not decided
+  in this release.
+
+### Added — `mcp.tool.model` / `gen_ai.response.model` validation (ADR 019 Part 2)
+
+**This is new behavior that can change what a call reports, not just a
+new diagnostic.** Before this release, a tool result's `model` field
+reached the span completely unvalidated, whatever it was. If you have a
+provider/deployment whose model identifiers use a character outside
+`[A-Za-z0-9._:/@-]`, or that (implausibly, but possibly) exceed 256
+characters, upgrading will make `mcp.tool.model`/`gen_ai.response.model`
+disappear from those calls' spans and `mcp.tool.pricing_status` flip from
+whatever it was to `"unknown"` — even for an otherwise-legitimate, real
+model id. The allowlist was deliberately built generous (see below) and
+verified against known provider conventions, but it's still new, and a
+one-time `diag.warn()` names when this happens (shape only, never the
+value) so it's discoverable rather than a silent metric/span change.
+
+- A tool result's declared model field is now checked against a 256-
+  character length cap and a `[A-Za-z0-9._:/@-]` allowlist — verified
+  against every `DEFAULT_PRICING` key and `normalizeModelName()`'s
+  documented `provider/model` input contract, deliberately generous —
+  before it can reach `mcp.tool.model`, `gen_ai.response.model`,
+  `calculateCost()`, or either metric label
+  (`mcp.tool.tokens.total`/`mcp.tool.cost.total`).
+- A rejected value is never a silent drop: `mcp.tool.pricing_status` is
+  set to `"unknown"` (the same status a legitimately unrecognized model
+  already produces), and a one-time `diag.warn()` fires per
+  `instrumentMcpServer()` call, reporting shape only — length, and which
+  check failed — never the rejected value itself.
+- `budgetTracker.recordUnpriced()` now receives the validated (possibly
+  `undefined`) model rather than the raw tool-result value, closing a
+  second leak path through its own pre-existing warning that would
+  otherwise have echoed a rejected value verbatim.
+- `costTracking.pricing`/`pricingTable` override keys are unaffected —
+  operator-authored config, never subject to this gate.
+
+### Fixed — `mcp.failure.error_class` uncapped length, `mcp.failure.validation_paths` dynamic-key leak (known-gaps entry 10)
+
+- `mcp.failure.error_class` is now capped at 128 characters
+  (`fingerprint/compose.js`'s new `MAX_ERROR_CLASS_LENGTH`) — length-
+  bounded only, not pattern-scrubbed; a non-string `.name` is coerced to
+  a string before capping rather than thrown. ADR 004's note calling the
+  underlying value "low-cardinality" is updated to flag that as an
+  assumption, not an enforced property.
+- `mcp.failure.validation_paths` format 1 (the raw Zod issues array, SDK
+  ≤1.29.0) now redacts a non-identifier-shaped path segment — a
+  `z.record()` schema's runtime key — to the placeholder `<KEY>` instead
+  of surfacing it verbatim, matching the identifier-only gate formats 2/3
+  already applied. Numeric (array-index) segments are never redacted.
+
 ## 0.12.0
 
 Agent Thrash Detection gains a new, narrower session-identity fallback for

package/README.md

@@ -461,6 +461,59 @@ examples/fingerprint-demo.js`). Not yet wired through
 `computeFingerprint` directly rather than configuring the automatic
 per-call-site wrapping; tracked in the roadmap below.
 
+## Error recording (v0.13.0+)
+
+Every thrown `tools/call`/`tools/list` error goes through
+`span.recordException(err)` (an OpenTelemetry SDK method, not one of this
+library's own attributes) plus `span.setStatus({ code: ERROR, message:
+err.message })` — unconditionally, whether or not `fingerprinting` is
+enabled. By default that means `err.message` and `err.stack` land on the
+span exactly as thrown. `errorRecording.mode` controls this:
+
+| Mode | `exception.message` / status message | `exception.stacktrace` | When to use |
+|---|---|---|---|
+| `'full'` (default) | Raw `err.message`, unmodified | Raw `err.stack`, unmodified | Today's behavior, unchanged — matches what every other OTel-instrumented library in the same trace does for the same kind of event |
+| `'normalized'` | `normalizeMessage(err.message)` — the exact scrubbing pipeline (`src/fingerprint/normalize/message.js`) fingerprinting already runs before hashing: UUIDs, emails, URLs, IPs, timestamps, filesystem paths, hex runs, quoted ids | Reconstructed from `parseAndNormalizeStack()` (`src/fingerprint/normalize/stack.js`) — keeps every function name/file/line, strips only the local `cwd` prefix (and collapses `node_modules` package versions) | Tool results come from third-party or unaudited MCP servers and you want the same scrubbing fingerprinting already trusts, applied to the raw exception content too |
+| `'none'` | Not set — `span.setStatus({ code: ERROR })` with no message, the same pattern already used for tool-level `isError: true` failures | Not set | You rely entirely on `mcp.failure.*` (category/fingerprint/signature — already hashed/normalized) and don't want any free-text exception content on the span at all |
+
+No mode mutates the original `err` — both call sites rethrow it
+afterward, so `'normalized'`/`'none'` build the exception event
+independently rather than editing `err.message`/`err.stack` in place.
+`error.type`/`exception.type` (`err.name`) is capped at 128 characters
+unconditionally in every mode — the same cap `mcp.failure.error_class`
+uses — since a length cap on a class-identifier field costs a
+well-behaved tool nothing, unlike message/stack content.
+
+**`'normalized'` is targeted scrubbing, not general-purpose redaction —
+read this before treating it as a PII filter.** `normalizeMessage()`
+matches specific, structured shapes: UUIDs, email addresses, URLs,
+IPv4/IPv6 addresses, ISO-8601/Unix timestamps, filesystem paths, long hex
+runs, and quoted alphanumeric ids (8–64 chars, mixed letters/digits). It
+does not recognize sensitive content in general. An API key in a format
+none of those patterns match (a bare, unquoted token with no digit in it,
+or a custom prefix scheme), or a customer's name embedded in ordinary
+prose ("could not process request for Jane Smith"), passes through
+`'normalized'` mode completely unchanged — identical to what `'full'`
+mode would put on the span. Treat `'normalized'` as "the same scrubbing
+fingerprinting already trusts for hashing," not as a guarantee that
+whatever a tool's error messages contain is safe to record; if a tool's
+errors routinely carry sensitive free text these patterns don't happen to
+match, `'none'` is the only mode that keeps message/stack content off the
+span entirely.
+
+**Default stays `'full'` through all of `0.x`.** Changing it would alter
+what every trace backend renders for the single highest-traffic failure
+path in this library, silently, for every existing deployment that
+doesn't opt in — see ADR 019 Part 1 (`docs/adr/019-raw-content-on-spans.md`)
+for the full argument, including why the default is expected to flip to
+`'normalized'` at `1.0`, not before.
+
+### Configuration
+
+| Option | Env var | Type | Default | Description |
+|---|---|---|---|---|
+| `mode` | `OTEL_MCP_ERROR_RECORDING_MODE` | `'full'` \| `'normalized'` \| `'none'` | `'full'` | See table above. An unrecognized value falls back to `'full'` silently, same as every other `OTEL_MCP_*` env var |
+
 ## Cost & Token Attribution (v0.5.0)
 
 MCP tools increasingly wrap LLM calls themselves — a tool that
@@ -569,7 +622,7 @@ stricter, not the runtime.
 | `mcp.tool.tokens.input` | Custom | Input tokens consumed | 1000 |
 | `mcp.tool.tokens.output` | Custom | Output tokens produced | 500 |
 | `mcp.tool.tokens.total` | Custom | input + output | 1500 |
-| `mcp.tool.model` | Custom | Detected model name | "claude-sonnet-5" |
+| `mcp.tool.model` | Custom | Detected model name, gated by a length/shape check (v0.13.0) — see below | "claude-sonnet-5" |
 | `gen_ai.response.model` | Standard (GenAI semconv)[^5] | Same value as `mcp.tool.model`, co-emitted for dashboard compatibility | "claude-sonnet-5" |
 | `mcp.tool.pricing_status` | Custom[^7] | `"known"` \| `"unknown"` \| `"user_override"` — set whenever token usage was extracted, even with no model detected | "known" |
 | `mcp.tool.cost.usd` | Custom | Estimated cost, from `calculateCost()` | 0.0105 |
@@ -589,6 +642,37 @@ attributes only appear when a cost was calculated *and* a configured
 limit was crossed. Source of truth: `src/attributes.js` and
 `src/instrument.js`'s `applyCostAttribution()`.
 
+### Model identifier validation (v0.13.0)
+
+A tool result's declared model field (`result.model`, `result.usage.model`,
+`result._meta.model`, or the same read out of JSON in
+`result.content[0].text`) is tool-result content, not library-computed
+metadata like everything else `applyCostAttribution()` puts on a span — so
+before it can reach `mcp.tool.model`, `gen_ai.response.model`,
+`calculateCost()`, or a metric label
+(`mcp.tool.tokens.total`/`mcp.tool.cost.total`), it has to pass a length
+cap (256 characters) and character allowlist
+(`/^[A-Za-z0-9._:/@-]{1,256}$/`). The allowlist is deliberately generous —
+verified against every `DEFAULT_PRICING` key *and* `normalizeModelName()`'s
+documented `provider/model` input contract (e.g.
+`"Anthropic/Claude-Opus-4-7"`), plus headroom for conventions like a full
+Bedrock ARN or a Vertex AI `@version` suffix — because silently rejecting a
+legitimate model name is a worse failure than admitting a few characters
+no known provider convention actually uses.
+
+**A rejected value is never a silent drop.** `mcp.tool.pricing_status` is
+set to `"unknown"` — the same status a legitimately unrecognized model
+already produces (see the footnote above) — and a `diag.warn()` fires
+once per `instrumentMcpServer()` call, reporting shape only (length, and
+whether length or character class failed), **never the rejected value
+itself**: echoing a malformed model id into log output would just move
+this exact problem from spans into logs instead of closing it. Token
+counts (`mcp.tool.tokens.*`) are unaffected either way — they're set
+before this gate runs. `costTracking.pricing`/`pricingTable` override keys
+(operator-authored config) are never subject to this check — only
+tool-result content is. Full design: ADR 019 Part 2
+(`docs/adr/019-raw-content-on-spans.md`).
+
 ### Metrics
 
 Two more `mcp.tool.*` metrics, via the same API-only pattern as the four
@@ -1746,6 +1830,56 @@ useful today, for free, to any client that already sets `_meta` in this
 shape; the client-side half is tracked as future work, not implied as
 solved by this release.
 
+## What this library records — read this before routing spans anywhere sensitive data isn't already allowed
+
+This is a description of what happens today, not a claim about a specific
+threat model this library has verified it covers.
+
+opentel-mcp forwards what your tools and their thrown exceptions actually
+produce. It does not invent, infer, or independently verify tool-result
+content — if a tool's handler throws `new Error('user ' + email + ' not
+found')`, or a tool result puts a credential in a field this library
+reads, that content is exactly what reaches your telemetry backend. Three
+channels carry it:
+
+- **`span.recordException(err)` / `span.setStatus({ message })`** on every
+  thrown `tools/call`/`tools/list` error — `exception.message` and
+  `exception.stacktrace` are set from `err.message`/`err.stack` verbatim
+  by default. `errorRecording.mode` controls this; see "Error recording"
+  above.
+- **`mcp.tool.model` / `gen_ai.response.model`** — a tool result's own
+  declared model field, admitted once it passes a length/character-shape
+  check (v0.13.0). The check bounds shape, not content: a well-formed but
+  still arbitrary string from a tool result reaches the span. See "Cost &
+  Token Attribution" → "Model identifier validation" above.
+- **`mcp.failure.error_class`** (length-capped at 128 characters, not
+  pattern-scrubbed) and **`mcp.failure.validation_paths`** (a schema's
+  dynamic/record keys replaced with the placeholder `<KEY>`) — both
+  already hardened; see `docs/known-gaps.md` entry 10.
+
+**This isn't unique to opentel-mcp.** OpenTelemetry's own semantic
+conventions mark `exception.message` as an attribute that "may contain
+sensitive information" and still specify recording it by default —
+every other OTel-instrumented library sharing the same trace (an HTTP
+client, a DB driver, a queue consumer) records `err.message`/`err.stack`
+the same way, unscrubbed, through the same `recordException()` call.
+opentel-mcp matches that ecosystem default rather than silently diverging
+from it. What it adds on top: `errorRecording.mode` lets you choose
+`'normalized'` (targeted scrubbing — the same structured patterns
+fingerprinting matches: UUIDs, emails, URLs, IPs, timestamps, paths,
+quoted ids; **not** a general-purpose PII filter, so freeform sensitive
+text — a customer's name in prose, an API key in a format none of those
+patterns match — still reaches the span unchanged, see "Error recording"
+above) or `'none'` (record neither) instead of `'full'` — a level of
+operator control most peer instrumentations don't offer for this path.
+Full reasoning, including why the default doesn't change in this
+release: ADR 019 (`docs/adr/019-raw-content-on-spans.md`).
+
+This is a data-handling property of an observability library, not a
+security control opentel-mcp is claiming to provide — it doesn't
+authenticate, encrypt, or restrict who can read your traces; that's your
+tracing backend's job.
+
 ## Configuration
 
 All options passed to `instrumentMcpServer(server, options)`. Source of
@@ -1762,9 +1896,11 @@ truth: `src/config.js`.
 | `costTracking` | object | see below | Controls cost/token attribution[^9] — see "Cost & Token Attribution" above |
 | `thrashDetection` | object | see below | Controls Agent Thrash Detection[^10] — see "Agent Thrash Detection" above. Requires `fingerprinting: true` |
 | `schemaDrift` | object | see below | Controls tool schema drift detection[^11] — see "Tool schema drift detection" above. `enabled: true` by default changes `instrumentMcpServer()`'s throw behavior on upgrade — see that section's "Behavior change on upgrade" |
+| `errorRecording` | object | see below | Controls what raw exception content reaches `recordException()`/`setStatus()`[^12] — see "Error recording" above |
 
 [^10]: `{ enabled?, threshold?, windowMs?, maxTrackedKeys?, entryTtlMs?, reEmitAfter?, assumeSingleSession? }`, all fields optional, individually defaulted, and individually overridable via an `OTEL_MCP_THRASH_*` env var — see "Agent Thrash Detection" → "Configuration" above for the full table.
 [^11]: `{ enabled?, maxTrackedTools? }`, all fields optional, individually defaulted, and individually overridable via an `OTEL_MCP_SCHEMA_DRIFT_*` env var — see "Tool schema drift detection" → "Configuration" above for the full table.
+[^12]: `{ mode?: 'full' | 'normalized' | 'none' }`, defaulted to `'full'`, individually overridable via `OTEL_MCP_ERROR_RECORDING_MODE` — see "Error recording" → "Configuration" above for the full table.
 
 [^9]: `{ enabled?: boolean; pricingTable?: PricingTable; extractor?: UsageExtractor; budget?: { perSessionUsd?: number; perToolUsd?: number } }`, all fields optional and individually defaulted — `{ enabled: true, pricingTable: DEFAULT_PRICING, extractor: defaultExtractor }` with budget tracking off.
 [^2]: Required only when `setupNodeSdk` is `true`. Has no effect otherwise — the host app's registered `TracerProvider` owns the resource; passing it anyway logs a one-time `diag.warn`.
@@ -2181,7 +2317,7 @@ pragmatic choice rather than a spec-pure one.
   revision 2026-07-28, v0.10.0+; see "MCP v2 support" above for what's
   covered and `docs/known-gaps.md` entries 6 and 8 for what isn't yet)
 - @opentelemetry/api ^1.9.0
-- 748 tests, 744 passing + 4 intentionally skipped (`npm test`) — see `test/`
+- 948 tests, 944 passing + 4 intentionally skipped (`npm test`) — see `test/`
 - `npm run typecheck` (`tsc --noEmit`) type-checks the public `.d.ts`
   surface (`src/index.d.ts` and friends) — see CONTRIBUTING.md
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opentel-mcp",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "One-line OpenTelemetry instrumentation for Model Context Protocol (MCP) servers",
   "type": "module",
   "main": "src/index.js",

package/src/config.js

@@ -9,6 +9,7 @@ import { defaultExtractor } from './cost/extractor.js';
 import { normalizeModelName } from './cost/calculator.js';
 import { resolveThrashConfig } from './thrash/config.js';
 import { resolveSchemaDriftConfig } from './schema-drift/config.js';
+import { resolveErrorRecordingConfig } from './error-recording/config.js';
 
 /**
  * @typedef {object} CostTrackingOptions
@@ -84,6 +85,19 @@ import { resolveSchemaDriftConfig } from './schema-drift/config.js';
  *   `enabled: false` (or the default when this option is omitted) is a true no-op: tools/list is not
  *   wrapped at all, unlike thrashDetection/costTracking whose disabled state still wraps tools/call for
  *   other reasons and merely skips inner logic.
+ * @property {Partial<import('./error-recording/config.js').ErrorRecordingConfig>} [errorRecording] - Controls
+ *   what a THROWN exception (not a tool-level `isError: true` result, which never carries a JS Error and is
+ *   unaffected) puts on the mcp.tool.call / tools/list span (ADR 019, docs/adr/019-raw-content-on-spans.md
+ *   Part 1, v0.13.0): `{ mode: 'full' | 'normalized' | 'none' }`. Defaults to `{ mode: 'full' }` —
+ *   byte-identical to every release before v0.13.0 (span.recordException(err) plus setStatus({ message:
+ *   err.message }), uncapped). `'normalized'` reuses fingerprint/normalize/message.js's normalizeMessage()
+ *   for the exception message and fingerprint/normalize/stack.js's parseAndNormalizeStack() for the
+ *   stacktrace (cwd-stripped, node_modules-version-collapsed) — no new scrubbing pipeline. `'none'` sets
+ *   only the ERROR status code, no message, no exception event — the same pattern already used for a
+ *   tool-level isError: true failure. Also settable via the `OTEL_MCP_ERROR_RECORDING_MODE` environment
+ *   variable (lower precedence than this option), same OTEL_MCP_<FEATURE>_ prefix pattern as
+ *   OTEL_MCP_THRASH_ and OTEL_MCP_SCHEMA_DRIFT_; an unrecognized value from either source falls back to
+ *   'full' silently, never a throw.
  * @property {string} [instanceKey] - Host-supplied stable identifier for one logical service (ADR 012,
  *   docs/adr/012-tracker-lifecycle-and-shared-state.md, Option C — Phase 2: this option and its wiring).
  *   When provided, the four in-memory trackers this library keeps per instrumented server — budget
@@ -259,6 +273,7 @@ export function resolveOptions(options) {
     },
     thrashDetection: resolveThrashConfig(opts.thrashDetection),
     schemaDrift: resolveSchemaDriftConfig(opts.schemaDrift),
+    errorRecording: resolveErrorRecordingConfig(opts.errorRecording),
     instanceKey: resolveInstanceKey(opts.instanceKey, process.env[ENV_INSTANCE_KEY]),
   };
 }

package/src/cost/calculator.js

@@ -18,6 +18,72 @@ export function normalizeModelName(model) {
   return slashIndex === -1 ? lower : lower.slice(slashIndex + 1);
 }
 
+// ADR 019 Part 2 (docs/adr/019-raw-content-on-spans.md, v0.13.0 Phase 2):
+// usage.model is tool-RESULT content, not library-computed metadata like
+// everything else applyCostAttribution() (instrument.js) puts on a span —
+// so it's gated through this allowlist before it can ever reach
+// mcp.tool.model/gen_ai.response.model or a metric label (metrics.js's
+// recordTokens()/recordCost() both key a label off it too, so an
+// unvalidated value would be a metric-cardinality hazard, not just a span
+// content one).
+//
+// Verified empirically against two real contracts, not assumed from
+// provider docs: (1) every DEFAULT_PRICING key (pricing.js) matches a
+// narrower `[a-z0-9-]` set, but (2) normalizeModelName() above already
+// documents AND tests (test/cost/calculator.test.js) a REQUIRED
+// "provider/model" input shape ("Anthropic/Claude-Opus-4-7") that no
+// DEFAULT_PRICING key itself contains — a narrow, table-derived allowlist
+// would reject input this library already advertises support for. `.`/
+// `:`/`@` are additionally admitted for real-world provider conventions
+// this investigation did not verify live (Bedrock's
+// `anthropic.claude-3-sonnet-20240229-v1:0` / ARN form, Vertex AI's
+// `text-bison@001`) — deliberately generous: silently rejecting a
+// legitimate model is a worse failure mode than admitting a few
+// characters no currently-known convention actually uses. See
+// isValidModelId()'s only caller (instrument.js's applyCostAttribution())
+// for what "rejected" actually does, which is never a silent drop.
+export const MODEL_ID_MAX_LENGTH = 256;
+const MODEL_ID_RE = new RegExp(`^[A-Za-z0-9._:/@-]{1,${MODEL_ID_MAX_LENGTH}}$`);
+
+/**
+ * Whether `value` is shaped like a real model identifier: a non-empty
+ * string, at most {@link MODEL_ID_MAX_LENGTH} characters, containing only
+ * alphanumerics and `.`/`_`/`:`/`/`/`@`/`-` — see this module's own
+ * comment above `MODEL_ID_MAX_LENGTH` for why this specific set. Does NOT
+ * check whether `value` resolves to a `DEFAULT_PRICING` entry —
+ * `mcp.tool.pricing_status: "unknown"` already exists to represent a
+ * real, valid model name with no known price (ADR 016 point 4); this
+ * function is a shape gate, not a pricing-table membership check.
+ *
+ * @param {unknown} value
+ * @returns {value is string}
+ */
+export function isValidModelId(value) {
+  return typeof value === 'string' && MODEL_ID_RE.test(value);
+}
+
+/**
+ * Describes, in shape-only terms, why `value` failed {@link isValidModelId}
+ * — a length, or "not a string"/"empty string" — and NEVER the value
+ * itself. Used only for a one-time diagnostic (instrument.js's
+ * applyCostAttribution(), ADR 019 Part 2): echoing the rejected value
+ * there would relocate this whole gate's problem from spans into logs
+ * instead of closing it, so this deliberately returns shape and nothing
+ * else — see that function's own warnRejectedModel() for the full
+ * reasoning.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function describeInvalidModelId(value) {
+  if (typeof value !== 'string') return 'not a string';
+  if (value.length === 0) return 'empty string';
+  if (value.length > MODEL_ID_MAX_LENGTH) {
+    return `length ${value.length}, expected 1-${MODEL_ID_MAX_LENGTH} identifier-shaped characters`;
+  }
+  return `length ${value.length}, contains a disallowed character`;
+}
+
 /**
  * @param {unknown} value
  * @returns {value is number}

package/src/error-recording/config.js

@@ -0,0 +1,74 @@
+/**
+ * @module error-recording/config
+ * Options parsing and defaults for exception-recording mode (ADR 019,
+ * docs/adr/019-raw-content-on-spans.md — Part 1, v0.13.0 Phase 1).
+ *
+ * Mirrors src/thrash/config.js's and src/schema-drift/config.js's pattern
+ * exactly: precedence, highest to lowest, is an explicit field on the
+ * `partial` argument, then the field's `OTEL_MCP_ERROR_RECORDING_*` env
+ * var, then the hardcoded default. An invalid or unparseable value from
+ * either source is treated exactly like an absent one — silent fallback
+ * to the next source, never a throw. `mode` is this module's only field
+ * (unlike thrash/schema-drift's several), so `pick()`'s multi-type
+ * dispatch (see those two modules' `BOOLEAN_FIELDS` Set) has nothing to
+ * dispatch between here — this module reads the one env var directly.
+ *
+ * The small `resolveMode()` helper below is not imported from either
+ * sibling config module — those don't export it, and this project's own
+ * convention (see schema-drift/config.js's own docblock, and
+ * fingerprint/hash.js's FALLBACK_FINGERPRINT duplication precedent it
+ * cites) is to duplicate a small, self-contained primitive rather than
+ * couple otherwise-unrelated feature config modules together.
+ */
+
+/**
+ * @typedef {import('./types.d.ts').ErrorRecordingConfig} ErrorRecordingConfig
+ */
+
+const ENV_PREFIX = 'OTEL_MCP_ERROR_RECORDING_';
+const ENV_MODE = `${ENV_PREFIX}MODE`;
+
+const VALID_MODES = new Set(['full', 'normalized', 'none']);
+
+/** @type {ErrorRecordingConfig} */
+const DEFAULTS = {
+  mode: 'full',
+};
+
+/**
+ * Resolves `mode` to one of `VALID_MODES`, or `fallback` if `value` isn't
+ * one — an unrecognized string (a typo, e.g. `'normalised'`) degrades to
+ * the default exactly like a missing value, never a throw, matching this
+ * codebase's general "invalid config degrades to the next source" env-var
+ * discipline (thrash/config.js, schema-drift/config.js).
+ *
+ * @param {unknown} value
+ * @param {ErrorRecordingConfig['mode']} fallback
+ * @returns {ErrorRecordingConfig['mode']}
+ */
+function resolveMode(value, fallback) {
+  return typeof value === 'string' && VALID_MODES.has(value) ? /** @type {ErrorRecordingConfig['mode']} */ (value) : fallback;
+}
+
+/**
+ * @param {Partial<ErrorRecordingConfig> | undefined} partial
+ * @returns {unknown} `partial.mode` if present, else the env var's raw string, else undefined (caller applies the default).
+ */
+function pickMode(partial) {
+  if (partial && partial.mode !== undefined) return partial.mode;
+  return process.env[ENV_MODE];
+}
+
+/**
+ * Validates and applies defaults to raw error-recording options. Never
+ * throws — the one field independently falls back to its default on
+ * anything other than a valid, recognized mode string.
+ *
+ * @param {Partial<ErrorRecordingConfig>} [partial]
+ * @returns {ErrorRecordingConfig}
+ */
+export function resolveErrorRecordingConfig(partial) {
+  return {
+    mode: resolveMode(pickMode(partial), DEFAULTS.mode),
+  };
+}

package/src/error-recording/types.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Shared type definitions for exception-recording mode (ADR 019,
+ * docs/adr/019-raw-content-on-spans.md — Part 1, v0.13.0 Phase 1).
+ *
+ * Hand-written, not a compiled build artifact — this project ships plain
+ * JS with no TypeScript build step (see CONTRIBUTING.md). {@link ErrorRecordingConfig}
+ * is re-exported from src/index.d.ts (via instrumentMcpServer()'s
+ * `options.errorRecording`), the same pattern src/thrash/types.d.ts's
+ * `ThrashConfig` and src/schema-drift/types.d.ts's `SchemaDriftConfig`
+ * already establish: a hand-written interface here, kept in sync with
+ * src/error-recording/config.js's own JSDoc `@typedef` by hand, not by a
+ * build step.
+ */
+
+/**
+ * Resolved error-recording config — see src/error-recording/config.js's
+ * `resolveErrorRecordingConfig()`, which this mirrors field-for-field. All
+ * fields are required here (this is the RESOLVED shape, after
+ * defaults/env vars have been applied); {@link instrumentMcpServer}'s
+ * `errorRecording` option accepts `Partial<ErrorRecordingConfig>` — see
+ * src/index.d.ts. Same pattern as `ThrashConfig`/`SchemaDriftConfig`.
+ */
+export interface ErrorRecordingConfig {
+  /**
+   * Controls what a thrown exception (as opposed to a tool-level
+   * `isError: true` result, which never carries a JS `Error` and is
+   * unaffected by this option) puts on the `tools/call`/`tools/list`
+   * span, per ADR 019 Part 1:
+   *
+   * - `'full'` — `span.recordException(err)` plus `span.setStatus({
+   *   message: err.message })`, exactly as every release before
+   *   v0.13.0. `exception.message`/`exception.stacktrace` carry
+   *   `err.message`/`err.stack` verbatim, uncapped — matching the OTel
+   *   ecosystem's own default (see ADR 019's "What OpenTelemetry's own
+   *   semantic conventions say").
+   * - `'normalized'` — the same `exception` event shape, but
+   *   `exception.message` is run through `normalizeMessage()`
+   *   (`src/fingerprint/normalize/message.js` — the same
+   *   UUID/email/URL/IP/timestamp/path/hex/quoted-id scrubbing already
+   *   used before fingerprint hashing) and `exception.stacktrace` is
+   *   rebuilt from `parseAndNormalizeStack()`'s frames
+   *   (`src/fingerprint/normalize/stack.js` — cwd-stripped,
+   *   `node_modules` version-collapsed), never the raw `err.stack`.
+   * - `'none'` — `span.setStatus({ code: ERROR })` only: no `message`,
+   *   no `exception` event at all. The same pattern already used for a
+   *   tool-level `isError: true` failure.
+   *
+   * `error.type` is capped at 128 characters regardless of this
+   * setting — see ADR 019 Part 1, "`error.type` — closing ADR 004's
+   * open note as part of this design."
+   *
+   * @default 'full'
+   */
+  mode: 'full' | 'normalized' | 'none';
+}

package/src/fingerprint/attributes.js

@@ -21,6 +21,15 @@ export const ATTRIBUTE_KEYS = Object.freeze({
   SIGNATURE: 'mcp.failure.signature',
   CATEGORY: 'mcp.failure.category',
   ORIGIN: 'mcp.failure.origin',
+  /**
+   * `result.inputs.errorClass` — `err.name` (or a non-Error throwable's
+   * `.name`), e.g. `"TypeError"`, `"ZodError"`. Capped at 128 characters
+   * by `computeFingerprint()` (`fingerprint/compose.js`'s
+   * `MAX_ERROR_CLASS_LENGTH`) — length-bounded only, not pattern-scrubbed
+   * the way `normalizedMessage` is: this is the application/library's own
+   * error class name, whatever it set `.name` to, not free text this
+   * library controls the shape of (docs/known-gaps.md entry 10).
+   */
   ERROR_CLASS: 'mcp.failure.error_class',
   /**
    * ADR 007's channel dimension (`classifyFailureChannel()`,
@@ -42,6 +51,13 @@ export const ATTRIBUTE_KEYS = Object.freeze({
    * CHANNEL, additive and never part of the fingerprint hash: the path
    * text is already implicit in the hashed normalized message (see ADR
    * 009), so hashing it again would be redundant, not more correct.
+   *
+   * A path segment that isn't a schema-declared identifier (a
+   * `z.record()`/map schema's runtime key, e.g. an email used as an
+   * object key) is redacted to `<KEY>` rather than surfaced — see
+   * `PATH_SEGMENT_RE`'s comment in validation-paths.js (docs/known-gaps.md
+   * entry 10) for why a placeholder, not a dropped segment or a dropped
+   * path.
    */
   VALIDATION_PATHS: 'mcp.failure.validation_paths',
 });

package/src/fingerprint/classify/validation-paths.js

@@ -147,6 +147,51 @@ function extractJsonArraySubstring(text) {
   return null; // unbalanced -- never guess a truncated substring
 }
 
+// Known-gaps entry 10 (docs/known-gaps.md): unlike the two RENDERED
+// formats below (RENDERED_DOT_PATH_RE, V2_ISSUE_START_RE), this JSON
+// format's `path` array comes straight from a parsed ZodError with no
+// character restriction at all -- for a `z.record()`/map-shaped schema,
+// a failing issue's `path` includes the actual runtime KEY the caller
+// passed (e.g. an email address used as an object key), which is caller
+// data, not a schema-declared field name. `PATH_SEGMENT_RE` gates each
+// string segment against the same identifier-only shape the rendered
+// formats already require (RENDERED_DOT_PATH_RE without the `.`/`[...]`
+// chaining, since here each segment is already a separate array element,
+// not a joined string to split) -- a segment that doesn't match is, by
+// construction, not a schema-declared property name a tool author wrote,
+// so it's treated as a dynamic key and redacted.
+//
+// Numeric segments (array indices) are never redacted: Zod only ever
+// produces a `number` path segment for an array index, never for an
+// object/record key (JSON object keys are always strings, even for a
+// numeric-looking one) -- so a `number` segment is structurally always a
+// small integer index, never caller-chosen content.
+//
+// What "redacted" means was a real choice among three, argued here rather
+// than picked silently:
+//   - Drop the whole path. Loses the entire signal for exactly the
+//     validation failures a record-shaped schema exists to catch -- the
+//     one case this gap is about is also the one case this option throws
+//     away completely.
+//   - Drop just the offending segment. WRONG, not just lossy: joining the
+//     remaining segments produces a path that names a DIFFERENT, real
+//     field. `["users", "<dynamic-key>", "email"]` dropped down to
+//     `users.email` looks like a legitimate, confidently-reported path to
+//     a field named `email` directly under `users` -- a fabricated
+//     dot-path this feature's own "never guess" discipline (see this
+//     module's docblock) exists specifically to rule out.
+//   - Replace the segment with a fixed placeholder. Preserves the path's
+//     shape and depth (still says "the failure was inside a record-like
+//     value at this position") without leaking the key's content -- the
+//     same shape/anomaly-signal-without-content-capture tradeoff
+//     `mcp.tool.argument_count` already makes (`src/attributes.js`), and
+//     the same placeholder-substitution mechanism `normalizeMessage()`'s
+//     `NORMALIZE_STEPS` already uses for EMAIL/UUID/URL/etc.
+//     (`normalize/patterns.js`). Chosen: it's the only option that
+//     neither destroys the signal nor fabricates a wrong one.
+const PATH_SEGMENT_RE = /^[\w$]+$/;
+const REDACTED_PATH_SEGMENT = '<KEY>';
+
 /**
  * Parses `jsonText` and, only if EVERY element confidently looks like a
  * Zod issue (a plain object with both a `path` array of string/number
@@ -159,6 +204,12 @@ function extractJsonArraySubstring(text) {
  * more likely a sign this isn't really a Zod issues array at all than a
  * reason to keep only the matching ones.
  *
+ * Any string segment that isn't identifier-shaped (`PATH_SEGMENT_RE`) is
+ * replaced with `REDACTED_PATH_SEGMENT` before joining — see the
+ * constants' own comment above for why a placeholder, not a dropped
+ * segment or a dropped path. Numeric segments (array indices) are never
+ * redacted.
+ *
  * @param {string} jsonText
  * @returns {string[] | null}
  */
@@ -182,7 +233,10 @@ function parseZodIssuesArray(jsonText) {
     if (!Array.isArray(path) || path.length === 0) return null;
     if (!path.every((segment) => typeof segment === 'string' || typeof segment === 'number')) return null;
 
-    paths.push(path.join('.'));
+    const redactedPath = path.map((segment) =>
+      typeof segment === 'number' || PATH_SEGMENT_RE.test(segment) ? segment : REDACTED_PATH_SEGMENT,
+    );
+    paths.push(redactedPath.join('.'));
   }
   return paths;
 }

package/src/fingerprint/compose.js

@@ -23,6 +23,31 @@ import { DEFAULT_CLASSIFIERS, runClassifiers } from './classify/index.js';
 const HASH_INPUT_VERSION = 'v1';
 const DEFAULT_STACK_FRAMES = 5;
 
+// Known-gaps entry 10 (docs/known-gaps.md): `errorClass` is `err.name` (or
+// a non-Error throwable's `.name`), and unlike `normalizedMessage` above it
+// gets no NORMALIZE_STEPS scrubbing — it lands on `mcp.failure.error_class`
+// (fingerprint/attributes.js) and `error.type` (instrument.js) exactly as
+// whatever thrown value set it. In practice `.name` is almost always a
+// short, fixed class identifier ("TypeError", "ZodError"), but nothing in
+// the language enforces that — a tool author (or library it depends on)
+// can assign any string. Capped here, not scrubbed like a message: a class
+// name isn't expected to contain structured PII shapes (emails, ids, ...)
+// the way a free-text message is, so pattern-matching would be reaching
+// for a problem this value doesn't really have. Length is the actual
+// unbounded dimension, so that's what's bounded. This also caps what feeds
+// the fingerprint hash below, which is fine: two DIFFERENT long class
+// names sharing an identical first 128 characters colliding into the same
+// fingerprint is not a real-world scenario a normal class identifier ever
+// produces.
+//
+// Exported as of v0.13.0 (ADR 019 Part 1, docs/adr/019-raw-content-on-spans.md):
+// instrument.js's independent `error.type`/`exception.type` read of the
+// same underlying err.name (ATTR_ERROR_TYPE, and the 'normalized'
+// errorRecording.mode's exception event) reuses this exact constant
+// rather than a second, possibly-drifting copy of the number 128 — "one
+// shared, capped value," per that ADR's own wording.
+export const MAX_ERROR_CLASS_LENGTH = 128;
+
 /**
  * @param {FingerprintContext} [ctx]
  * @returns {FingerprintResult}
@@ -120,8 +145,9 @@ export function computeFingerprint(err, ctx, opts = {}) {
       category = 'dependency';
     }
 
+    const rawErrorClass = typeof coerced.name === 'string' ? coerced.name : String(coerced.name);
     const inputs = {
-      errorClass: coerced.name,
+      errorClass: rawErrorClass.slice(0, MAX_ERROR_CLASS_LENGTH),
       category,
       origin: ctx.origin,
       toolName: ctx.toolName ?? null,

package/src/fingerprint/types.d.ts

@@ -80,7 +80,7 @@ export interface NormalizedStackFrame {
 
 /** The normalized, low-cardinality inputs that get hashed into a fingerprint. */
 export interface FingerprintInputs {
-  /** e.g. `"TypeError"`, `"ZodError"`, `"MCPToolError"`. */
+  /** e.g. `"TypeError"`, `"ZodError"`, `"MCPToolError"`. Capped at 128 characters (compose.js's MAX_ERROR_CLASS_LENGTH) — unlike `normalizedMessage`, not pattern-scrubbed, only length-bounded. */
   readonly errorClass: string;
   readonly category: FailureCategory;
   readonly origin: FailureOrigin;

package/src/index.d.ts

@@ -1,6 +1,7 @@
 import type { CostTrackingOptions } from './cost/types.d.ts';
 import type { ThrashConfig, ThrashSummary } from './thrash/types.d.ts';
 import type { SchemaDriftConfig } from './schema-drift/types.d.ts';
+import type { ErrorRecordingConfig } from './error-recording/types.d.ts';
 import type { ObservationState } from './observation/types.d.ts';
 
 /**
@@ -113,6 +114,24 @@ export interface InstrumentOptions {
    */
   schemaDrift?: Partial<SchemaDriftConfig>;
 
+  /**
+   * Controls what a THROWN exception (not a tool-level `isError: true` result, which never carries a JS
+   * `Error` and is unaffected by this option) puts on the `tools/call`/`tools/list` span (ADR 019,
+   * `docs/adr/019-raw-content-on-spans.md` Part 1, v0.13.0).
+   *
+   * Defaults to `{ mode: 'full' }` — byte-identical to every release before v0.13.0:
+   * `span.recordException(err)` plus `span.setStatus({ message: err.message })`, both uncapped.
+   * `'normalized'` reuses `normalizeMessage()` (`src/fingerprint/normalize/message.js`) for the exception
+   * message and `parseAndNormalizeStack()` (`src/fingerprint/normalize/stack.js`) for the stacktrace
+   * (cwd-stripped, `node_modules` version-collapsed) — no new scrubbing pipeline. `'none'` sets only the
+   * `ERROR` status code, no message, no `exception` event.
+   *
+   * Also settable via the `OTEL_MCP_ERROR_RECORDING_MODE` environment variable (lower precedence than this
+   * option); an unrecognized value from either source falls back to `'full'` silently, never a throw. See
+   * {@link ErrorRecordingConfig} (`src/error-recording/types.d.ts`).
+   */
+  errorRecording?: Partial<ErrorRecordingConfig>;
+
   /**
    * Host-supplied stable identifier for one logical service (ADR 012,
    * `docs/adr/012-tracker-lifecycle-and-shared-state.md`, Option C). When provided, the four in-memory
@@ -395,6 +414,18 @@ export type { ThrashConfig, ThrashDetectedEvent, ThrashSummary, ThrashOffender }
 
 export type { SchemaDriftConfig, SchemaDriftKind, SchemaDriftEvent } from './schema-drift/types.d.ts';
 
+// --- Exception-recording mode (src/error-recording/) ---
+//
+// Re-exported here so TypeScript consumers get this type from the package
+// root instead of reaching into src/error-recording/* directly. See
+// src/error-recording/types.d.ts for the full shape documentation and ADR
+// 019 (docs/adr/019-raw-content-on-spans.md). Same posture as Agent
+// Thrash Detection / schema drift above — no runtime value re-exported:
+// resolveErrorRecordingConfig() is internal to src/config.js's wiring,
+// not part of the public API.
+
+export type { ErrorRecordingConfig } from './error-recording/types.d.ts';
+
 // --- Two-axis observation contract (src/observation/) ---
 //
 // Re-exported here so TypeScript consumers get these types from the

package/src/instrument.js

@@ -12,11 +12,13 @@ import { resourceFromAttributes } from '@opentelemetry/resources';
 import { resolveOptions } from './config.js';
 import { StderrSpanExporter } from './exporters/stderr.js';
 import { setupMeter } from './metrics.js';
-import { computeFingerprint } from './fingerprint/compose.js';
+import { computeFingerprint, MAX_ERROR_CLASS_LENGTH } from './fingerprint/compose.js';
 import { toSpanAttributes, ATTRIBUTE_KEYS } from './fingerprint/attributes.js';
 import { classifyFailureChannel } from './fingerprint/classify/channel.js';
 import { extractValidationPaths } from './fingerprint/classify/validation-paths.js';
-import { calculateCost, normalizeModelName } from './cost/calculator.js';
+import { normalizeMessage } from './fingerprint/normalize/message.js';
+import { parseAndNormalizeStack } from './fingerprint/normalize/stack.js';
+import { calculateCost, normalizeModelName, isValidModelId, describeInvalidModelId } from './cost/calculator.js';
 import { DEFAULT_PRICING_LAST_VERIFIED } from './cost/pricing.js';
 import { createBudgetTracker } from './cost/budget.js';
 import { extractTraceContext } from './tracecontext/extract.js';
@@ -464,6 +466,15 @@ export function instrumentMcpServer(input, options) {
   // resolveThrashSessionId() persist state across calls. See that
   // function's docblock for why this flag exists at all.
   const thrashSessionState = { hasSeenRealSessionId: false, hasWarnedFallbackUsed: false };
+  // Same "plain holder, not instanceKey-shared" reasoning as
+  // thrashSessionState immediately above (ADR 019 Part 2, v0.13.0 Phase
+  // 2): warnRejectedModel() (see applyCostAttribution()) is a low-stakes
+  // diagnostic, not correctness-critical accumulated state the way
+  // budgetTracker/thrashDetector are — firing again on a fresh instance
+  // under a fresh-Server-per-request deployment is the same known,
+  // accepted characteristic docs/known-gaps.md entry 6 already documents
+  // for thrashSessionState, not a new problem this introduces.
+  const costAttributionState = { warnedRejectedModel: false };
   // Additive to instrumentMcpServer()'s existing return contract (the same
   // input object, for chaining — see this function's own docblock): a
   // getThrashSummary() method attached the same way shutdown() is, just
@@ -563,9 +574,19 @@ export function instrumentMcpServer(input, options) {
           toolOutcomeCounter,
           server,
           kind,
+          resolved.errorRecording,
+          costAttributionState,
         );
       } else if (schema === v1.ListToolsRequestSchema && schemaDriftDetector) {
-        handler = wrapToolsListHandler(handler, tracer, schemaDriftDetector, schemaDriftEmitter, SCHEMA_DRIFT_SCOPE, kind);
+        handler = wrapToolsListHandler(
+          handler,
+          tracer,
+          schemaDriftDetector,
+          schemaDriftEmitter,
+          SCHEMA_DRIFT_SCOPE,
+          kind,
+          resolved.errorRecording,
+        );
       }
       return originalSetRequestHandler(schema, handler);
     };
@@ -605,9 +626,19 @@ export function instrumentMcpServer(input, options) {
           toolOutcomeCounter,
           server,
           kind,
+          resolved.errorRecording,
+          costAttributionState,
         );
       } else if (maybeHandler === undefined && method === TOOLS_LIST_METHOD && schemaDriftDetector) {
-        handlerOrSchemas = wrapToolsListHandler(handlerOrSchemas, tracer, schemaDriftDetector, schemaDriftEmitter, SCHEMA_DRIFT_SCOPE, kind);
+        handlerOrSchemas = wrapToolsListHandler(
+          handlerOrSchemas,
+          tracer,
+          schemaDriftDetector,
+          schemaDriftEmitter,
+          SCHEMA_DRIFT_SCOPE,
+          kind,
+          resolved.errorRecording,
+        );
       }
       return maybeHandler === undefined
         ? originalSetRequestHandler(method, handlerOrSchemas)
@@ -748,6 +779,51 @@ function extractSessionAndRequestId(kind, extraOrCtx) {
   return { sessionId: extraOrCtx?.sessionId, requestId: extraOrCtx?.requestId };
 }
 
+/**
+ * One-time diagnostic for a tool result's `model` field that failed
+ * isValidModelId()'s length/shape gate (ADR 019 Part 2,
+ * docs/adr/019-raw-content-on-spans.md, v0.13.0 Phase 2). Distinct from
+ * budgetTracker.recordUnpriced()'s own warning (src/cost/budget.js):
+ * that one describes a LATER, different condition (a real, valid model
+ * name that just doesn't resolve to a price) and only fires when a
+ * budget is actually configured. This one fires for any
+ * `costTracking.enabled` deployment, budget or not — "your cost/token
+ * attribution is silently missing a model" is worth knowing regardless
+ * of whether a budget guardrail is in play.
+ *
+ * CRITICAL, and the entire reason this function exists rather than just
+ * inlining a `diag.warn()` call with `value` in it: reports SHAPE ONLY —
+ * via describeInvalidModelId() (src/cost/calculator.js), never the
+ * rejected value itself. `diag.warn()` output routinely gets piped into
+ * a deployment's own logging pipeline; printing the offending string
+ * here would relocate this whole gate's problem from spans into logs
+ * instead of closing it.
+ *
+ * Fires at most once per `state` object — see applyCostAttribution()'s
+ * own docblock for why `state` (costAttributionState) is constructed
+ * fresh per instrumentMcpServer() call rather than instanceKey-shared.
+ * Never throws, matching every other diagnostic in this codebase.
+ *
+ * @param {unknown} value - The rejected `usage.model` value. Read only for its shape (typeof, length) —
+ *   never logged, never returned, never otherwise observable outside this function.
+ * @param {{ warnedRejectedModel: boolean }} state
+ */
+function warnRejectedModel(value, state) {
+  if (state.warnedRejectedModel) return;
+  state.warnedRejectedModel = true;
+
+  try {
+    diag.warn(
+      `opentel-mcp: a tool result's model field failed validation (${describeInvalidModelId(value)}) and was ` +
+        "excluded from mcp.tool.model / gen_ai.response.model / cost attribution; mcp.tool.pricing_status was " +
+        "set to 'unknown'. This warning fires once per instrumentMcpServer() call and deliberately never logs " +
+        'the value itself — see docs/adr/019-raw-content-on-spans.md Part 2.',
+    );
+  } catch {
+    // Never throw — see this function's own docblock.
+  }
+}
+
 /**
  * Best-effort cost/token attribution for one tool call's result, added on
  * top of the span and metrics that always fire (see wrapToolCallHandler
@@ -794,6 +870,22 @@ function extractSessionAndRequestId(kind, extraOrCtx) {
  * directly instead of inferring it from an attribute's absence. Passed to
  * recordTokens/recordCost too, for the same metric-level visibility.
  *
+ * v0.13.0 (ADR 019 Part 2, docs/adr/019-raw-content-on-spans.md): `usage.model`
+ * is tool-RESULT content, not library-computed metadata — before it's used
+ * ANYWHERE below (span attributes, calculateCost(), pricingOverrideKeys
+ * lookup, metric labels), it's gated through isValidModelId()
+ * (src/cost/calculator.js): a length/character allowlist, never a
+ * pricing-table membership check. A value that fails this gate is treated
+ * exactly like "no model detected" for every downstream purpose — the
+ * existing mcp.tool.pricing_status: "unknown" / budgetTracker.recordUnpriced()
+ * machinery already handles that case correctly, so a rejected value is
+ * never a silent drop, just a redirection into a path this function
+ * already had. warnRejectedModel() below additionally fires a one-time,
+ * SHAPE-ONLY diagnostic (never the rejected value itself — see that
+ * function's own docblock) distinct from budgetTracker.recordUnpriced()'s
+ * own warning, which describes a different, later condition and is gated
+ * on a budget being configured; this one isn't.
+ *
  * @param {import('@opentelemetry/api').Span} span
  * @param {ReturnType<import('./metrics.js').setupMeter> | null} metricsRecorder
  * @param {string | undefined} toolName
@@ -801,9 +893,12 @@ function extractSessionAndRequestId(kind, extraOrCtx) {
  * @param {*} result
  * @param {import('./config.js').CostTrackingOptions & { pricingOverrideKeys: Set<string> }} costTracking
  * @param {ReturnType<import('./cost/budget.js').createBudgetTracker>} budgetTracker
+ * @param {{ warnedRejectedModel: boolean }} costAttributionState - ADR 019 Part 2: one-time-warning state
+ *   for warnRejectedModel() below, constructed once per instrumentMcpServer() call (same non-instanceKey-shared
+ *   granularity as thrashSessionState — see that variable's own comment in instrumentMcpServer()).
  * @returns {{ tokensIn: number, tokensOut: number, costUsd: number } | null}
  */
-function applyCostAttribution(span, metricsRecorder, toolName, sessionId, result, costTracking, budgetTracker) {
+function applyCostAttribution(span, metricsRecorder, toolName, sessionId, result, costTracking, budgetTracker, costAttributionState) {
   if (!costTracking.enabled) return null;
 
   try {
@@ -813,33 +908,55 @@ function applyCostAttribution(span, metricsRecorder, toolName, sessionId, result
     span.setAttribute(ATTR_MCP_TOOL_TOKENS_INPUT, usage.inputTokens);
     span.setAttribute(ATTR_MCP_TOOL_TOKENS_OUTPUT, usage.outputTokens);
     span.setAttribute(ATTR_MCP_TOOL_TOKENS_TOTAL, usage.totalTokens);
-    if (usage.model) {
-      span.setAttribute(ATTR_MCP_TOOL_MODEL, usage.model);
-      span.setAttribute(ATTR_GEN_AI_RESPONSE_MODEL, usage.model);
+
+    // ADR 019 Part 2: usage.model is gated here, ONCE, before it reaches
+    // anything below — a rejected value (usage.model was present but
+    // isn't identifier-shaped) is treated identically to "no model
+    // detected" for every downstream purpose (validModel stays
+    // undefined), and warnRejectedModel() fires the one-time, shape-only
+    // diagnostic. usage.model === undefined (no model detected at all —
+    // the pre-existing, unrelated case) never calls warnRejectedModel:
+    // there's nothing rejected, just nothing found.
+    const modelIsValid = isValidModelId(usage.model);
+    if (usage.model !== undefined && !modelIsValid) {
+      warnRejectedModel(usage.model, costAttributionState);
+    }
+    const validModel = modelIsValid ? usage.model : undefined;
+
+    if (validModel) {
+      span.setAttribute(ATTR_MCP_TOOL_MODEL, validModel);
+      span.setAttribute(ATTR_GEN_AI_RESPONSE_MODEL, validModel);
     }
 
     let costUsd = null;
-    if (usage.model) {
-      costUsd = calculateCost(usage.inputTokens, usage.outputTokens, usage.model, costTracking.pricingTable);
+    if (validModel) {
+      costUsd = calculateCost(usage.inputTokens, usage.outputTokens, validModel, costTracking.pricingTable);
     }
 
     // ADR 016 point 4: provenance-based, computed against the same
     // normalized key calculateCost() itself looked up — 'unknown' covers
-    // both "no model detected at all" and "model detected but didn't
-    // resolve to a cost" (unrecognized, or a malformed override entry).
+    // "no model detected at all," "a rejected model field" (ADR 019 Part
+    // 2 — validModel is undefined either way), and "model detected but
+    // didn't resolve to a cost" (unrecognized, or a malformed override
+    // entry).
     const pricingStatus =
-      !usage.model || costUsd === null
+      !validModel || costUsd === null
         ? MCP_TOOL_PRICING_STATUS_UNKNOWN
-        : costTracking.pricingOverrideKeys.has(normalizeModelName(usage.model))
+        : costTracking.pricingOverrideKeys.has(normalizeModelName(validModel))
           ? MCP_TOOL_PRICING_STATUS_USER_OVERRIDE
           : MCP_TOOL_PRICING_STATUS_KNOWN;
     span.setAttribute(ATTR_MCP_TOOL_PRICING_STATUS, pricingStatus);
-    metricsRecorder?.recordTokens(toolName, usage.model, usage.totalTokens, pricingStatus);
+    // validModel, not usage.model: mcp.tool.model is also a metric LABEL
+    // here (metrics.js's recordTokens()/recordCost()), so a rejected
+    // value must never reach it either — an unvalidated string becoming a
+    // label is a cardinality hazard on top of the content-exposure one
+    // ADR 019 Part 2 is about.
+    metricsRecorder?.recordTokens(toolName, validModel, usage.totalTokens, pricingStatus);
 
     if (costUsd !== null) {
       span.setAttribute(ATTR_MCP_TOOL_COST_USD, costUsd);
       span.setAttribute(ATTR_MCP_TOOL_COST_CURRENCY, MCP_TOOL_COST_CURRENCY_USD);
-      metricsRecorder?.recordCost(toolName, usage.model, costUsd, pricingStatus);
+      metricsRecorder?.recordCost(toolName, validModel, costUsd, pricingStatus);
 
       const budgetResult = budgetTracker.recordAndCheck(sessionId, toolName, costUsd);
       if (budgetResult.exceeded) {
@@ -853,7 +970,21 @@ function applyCostAttribution(span, metricsRecorder, toolName, sessionId, result
       // never saw it. recordUnpriced() no-ops unless a budget is actually
       // configured, and warns at most once per tracker instance — see its
       // own docblock (src/cost/budget.js).
-      budgetTracker.recordUnpriced(usage.model);
+      //
+      // validModel, deliberately NOT usage.model: recordUnpriced()'s OWN
+      // pre-existing warning (cost/budget.js) names whatever `model` it's
+      // given verbatim (`isNonEmptyString(model) ? \`"${model}"\` : ...`)
+      // — it was written for "a real, short model name that just has no
+      // price," where that's safe. Passing the RAW rejected usage.model
+      // through unchanged here would let THAT warning re-leak the exact
+      // content warnRejectedModel() above was just careful not to —
+      // relocating ADR 019 Part 2's problem into a different diag.warn()
+      // call instead of closing it. validModel is undefined for a
+      // rejected value, which recordUnpriced() already renders as
+      // "(no model detected)" — an approximation ("rejected" collapses
+      // into "not detected"), accepted deliberately: warnRejectedModel()
+      // above is the one place that's supposed to say more, safely.
+      budgetTracker.recordUnpriced(validModel);
     }
 
     return { tokensIn: usage.inputTokens, tokensOut: usage.outputTokens, costUsd: costUsd ?? 0 };
@@ -1216,6 +1347,96 @@ function applyToolOutcomeThrown(toolOutcomeCounter) {
   }
 }
 
+/**
+ * Records a thrown exception onto `span` per `errorRecordingConfig.mode`
+ * (ADR 019 Part 1, docs/adr/019-raw-content-on-spans.md, v0.13.0 Phase 1).
+ * The only two call sites are the thrown-exception catch blocks in
+ * wrapToolCallHandler()/wrapToolsListHandler() below — a tool-level
+ * `isError: true` result never carries a JS Error at all and is
+ * unaffected by this option (see its own `span.setStatus({ code:
+ * SpanStatusCode.ERROR })` with no message, a few lines above in
+ * wrapToolCallHandler — the exact pattern 'none' mode below reuses).
+ *
+ * - `'full'` (default): `span.recordException(err)` +
+ *   `setStatus({ message: err?.message })` — byte-identical to every
+ *   release before v0.13.0. This is the literal two-line call the
+ *   catch blocks used inline before this function existed; taken
+ *   unconditionally, with no new branching evaluated first, whenever
+ *   mode is `'full'`.
+ * - `'none'`: `setStatus({ code: ERROR })` only — no message, no
+ *   `exception` event.
+ * - `'normalized'`: a hand-built `exception` event carrying the same
+ *   three keys `recordException()` itself would set
+ *   (`exception.type`/`exception.message`/`exception.stacktrace`), but
+ *   with `exception.message` run through `normalizeMessage()` and
+ *   `exception.stacktrace` rebuilt from `parseAndNormalizeStack()`'s
+ *   frames (cwd-stripped, `node_modules`-version-collapsed) — never the
+ *   raw `err.stack`. `err` itself is never mutated: both call sites
+ *   rethrow the original object afterward, and `computeFingerprint()` a
+ *   few lines later (when fingerprinting is enabled) reads
+ *   `err.message`/`err.stack` independently, on the real, unmutated
+ *   object.
+ *
+ * `error.type` (`ATTR_ERROR_TYPE`, set by each call site immediately
+ * after this call returns) is capped at `MAX_ERROR_CLASS_LENGTH`
+ * regardless of mode — see each call site's own comment. The native
+ * `exception.type` a `'full'`-mode `span.recordException(err)` call sets
+ * internally is deliberately NOT capped here: `'full'` mode is defined
+ * as byte-identical to pre-v0.13.0 behavior, so the native OTel SDK call
+ * is left completely untouched, uncapped exception.type included. Only
+ * `'normalized'` mode's hand-built event applies the cap to
+ * `exception.type` too (mirroring `recordException()`'s own
+ * `err.code?.toString() ?? err.name` derivation for what goes in that
+ * field), since that event is already being constructed by hand either
+ * way — there is no "untouched native call" to preserve for that mode.
+ *
+ * Never throws — matches this library's fail-open discipline for
+ * everything downstream of a real thrown error, the same guarantee
+ * `fingerprint/compose.js`'s `computeFingerprint()` already makes for
+ * the exact same `err`.
+ *
+ * @param {import('@opentelemetry/api').Span} span
+ * @param {unknown} err
+ * @param {import('./error-recording/config.js').ErrorRecordingConfig} errorRecordingConfig
+ */
+function recordThrownException(span, err, errorRecordingConfig) {
+  try {
+    if (errorRecordingConfig.mode === 'none') {
+      span.setStatus({ code: SpanStatusCode.ERROR });
+      return;
+    }
+
+    if (errorRecordingConfig.mode === 'normalized') {
+      const rawMessage = err?.message;
+      const message = typeof rawMessage === 'string' ? normalizeMessage(rawMessage) : undefined;
+
+      const rawStack = err?.stack;
+      const { frames } = parseAndNormalizeStack(typeof rawStack === 'string' ? rawStack : undefined, {
+        cwd: process.cwd(),
+      });
+      const stacktrace =
+        frames.length > 0
+          ? frames.map((frame) => `${frame.fn || '<anonymous>'}@${frame.file}:${frame.line ?? '?'}`).join('\n')
+          : undefined;
+
+      const exceptionType = String(err?.code ?? err?.name ?? 'Error').slice(0, MAX_ERROR_CLASS_LENGTH);
+
+      const attrs = { 'exception.type': exceptionType };
+      if (message !== undefined) attrs['exception.message'] = message;
+      if (stacktrace !== undefined) attrs['exception.stacktrace'] = stacktrace;
+      span.addEvent('exception', attrs);
+      span.setStatus({ code: SpanStatusCode.ERROR, message });
+      return;
+    }
+
+    // 'full' (default) — byte-identical to pre-v0.13.0 behavior.
+    span.recordException(err);
+    span.setStatus({ code: SpanStatusCode.ERROR, message: err?.message });
+  } catch {
+    // Never throw — see this function's own docblock.
+  }
+}
+
 /**
  * Wraps a tools/call handler in a span covering its execution, plus the
  * mcp.tool.* metrics (see src/metrics.js). This sits as the innermost layer
@@ -1309,6 +1530,11 @@ function applyToolOutcomeThrown(toolOutcomeCounter) {
  * @param {'v1' | 'v2'} kind - ADR 015 Phase 2: which SDK `server` came from, resolved once by
  *   detectServerKind() at instrument time — determines how `sessionId`/`requestId` are read off
  *   the handler's second argument (`extra` for v1, `ctx` for v2 — see extractSessionAndRequestId()).
+ * @param {import('./error-recording/config.js').ErrorRecordingConfig} errorRecordingConfig - ADR 019 Part 1
+ *   (v0.13.0): controls what the thrown-exception branch below puts on the span — see
+ *   recordThrownException()'s own docblock.
+ * @param {{ warnedRejectedModel: boolean }} costAttributionState - ADR 019 Part 2 (v0.13.0): threaded
+ *   through to applyCostAttribution() — see that function's own docblock and warnRejectedModel()'s.
  */
 function wrapToolCallHandler(
   handler,
@@ -1325,6 +1551,8 @@ function wrapToolCallHandler(
   toolOutcomeCounter,
   server,
   kind,
+  errorRecordingConfig,
+  costAttributionState,
 ) {
   return (request, extra) => {
     const toolName = request?.params?.name;
@@ -1417,7 +1645,16 @@ function wrapToolCallHandler(
               span.setAttribute(ATTRIBUTE_KEYS.VALIDATION_PATHS, validationPaths);
             }
           }
-          const usage = applyCostAttribution(span, metricsRecorder, toolName, sessionId, result, costTracking, budgetTracker);
+          const usage = applyCostAttribution(
+            span,
+            metricsRecorder,
+            toolName,
+            sessionId,
+            result,
+            costTracking,
+            budgetTracker,
+            costAttributionState,
+          );
           // ADR 007: a 'protocol.output' failure recovered above (a
           // McpServer-disguised output-schema bug) must not be counted as
           // thrash here either, same as the thrown branch below —
@@ -1446,7 +1683,7 @@ function wrapToolCallHandler(
           );
         } else {
           span.setStatus({ code: SpanStatusCode.OK });
-          applyCostAttribution(span, metricsRecorder, toolName, sessionId, result, costTracking, budgetTracker);
+          applyCostAttribution(span, metricsRecorder, toolName, sessionId, result, costTracking, budgetTracker, costAttributionState);
           if (thrashSessionId !== null) {
             applyThrashSuccessClear(thrashConfig, thrashDetector, thrashSessionId, toolName);
           }
@@ -1455,9 +1692,16 @@ function wrapToolCallHandler(
         return result;
       } catch (err) {
         applyToolOutcomeThrown(toolOutcomeCounter);
-        span.recordException(err);
-        span.setStatus({ code: SpanStatusCode.ERROR, message: err?.message });
-        const errorType = err?.name ?? 'Error';
+        recordThrownException(span, err, errorRecordingConfig);
+        // ADR 019 Part 1: capped at MAX_ERROR_CLASS_LENGTH unconditionally,
+        // regardless of errorRecordingConfig.mode — a length cap on a
+        // class-identifier field costs a well-behaved tool nothing, so
+        // there's no default-behavior tension to gate it behind (contrast
+        // recordThrownException()'s own mode branching, which does gate
+        // message/stacktrace CONTENT). Same coercion compose.js's
+        // errorClass applies (a non-string .name is stringified, not
+        // thrown on) — see fingerprint/compose.js's rawErrorClass.
+        const errorType = String(err?.name ?? 'Error').slice(0, MAX_ERROR_CLASS_LENGTH);
         span.setAttribute(ATTR_ERROR_TYPE, errorType);
 
         let failureCategory = '';
@@ -1549,8 +1793,13 @@ function wrapToolCallHandler(
  * @param {string} schemaDriftScope - Fixed per instrumented server instance — see instrumentMcpServer().
  * @param {'v1' | 'v2'} kind - ADR 015 Phase 2: see wrapToolCallHandler's own `kind` param and
  *   extractSessionAndRequestId() — same requestId-only extraction, no sessionId use here.
+ * @param {import('./error-recording/config.js').ErrorRecordingConfig} errorRecordingConfig - ADR 019 Part 1
+ *   (v0.13.0): see wrapToolCallHandler's own param and recordThrownException()'s docblock. The thrown-
+ *   exception branch below is the only place this handler's own JS Error content reaches a span; a
+ *   schema-drift capture failure (caught separately just above) is diag.debug()-only and never reaches
+ *   the span at all, so it's unaffected by this option.
  */
-function wrapToolsListHandler(handler, tracer, schemaDriftDetector, schemaDriftEmitter, schemaDriftScope, kind) {
+function wrapToolsListHandler(handler, tracer, schemaDriftDetector, schemaDriftEmitter, schemaDriftScope, kind, errorRecordingConfig) {
   return (request, extra) => {
     return tracer.startActiveSpan(TOOLS_LIST_METHOD, { kind: SpanKind.SERVER }, async (span) => {
       span.setAttribute(ATTR_MCP_METHOD_NAME, TOOLS_LIST_METHOD);
@@ -1580,8 +1829,7 @@ function wrapToolsListHandler(handler, tracer, schemaDriftDetector, schemaDriftE
         span.setStatus({ code: SpanStatusCode.OK });
         return result;
       } catch (err) {
-        span.recordException(err);
-        span.setStatus({ code: SpanStatusCode.ERROR, message: err?.message });
+        recordThrownException(span, err, errorRecordingConfig);
         throw err;
       } finally {
         span.end();