mcpx: design — sampling trust boundary (reviewable, validated, honestly error-coded) #1834

Design: mcpx sampling trust boundary — reviewable, validated, and honestly error-coded

Design doc: files/designs/code-mcpx-sampling-trust-boundary.md in the keep-the-four-repos-healthy goal workspace (developing-today/code design architect, pass 10, 2026-10-28).
Origin: dezren39/nix#256 — sampling relay: human review, validation of results, error mapping (8 conformance rows). This design scopes only its remainder (audit below); no Drew direction decision is needed — nix#256's acceptance is explicit and its scope is conformance-only (sampling is deprecated in 2026-07-28; standing instruction is keep-working, add-nothing-new).

Problem

mcpx has no model, so sampling is a relay with a trust decision inside it: an upstream asks for a completion, something answering for the user produces one, and mcpx hands it back as if the user had spoken. Verified on main 528886eb:

1. A person cannot review a sampling request — the prompt is not shown. sampleViaBroker (pkgs/mcpx/internal/daemon/hooks.go ~L198-214) stores the request's system prompt as the broker question's Message (fallback: "<server> asks for a model completion") and the full request in the question's Schema field. But mcpx elicit's renderQuestion (pkgs/mcpx/internal/cli/elicit.go) renders Schema as a JSON Schema: describeSchema looks for properties, a sampling request has none, so the messages — the actual prompt — render as nothing and the answer example offered is '{}'. Routing never offers a person the question either: elicit.Route (internal/elicit/elicit.go ~L502-503) sends every Sample question to the agent audience unconditionally. Denial exists (decline is conformance-tested), but the spec's review rows have no surface. Gaps: sampling-app-review-ui, sampling-app-view-edit-prompts, sampling-app-review-responses, sampling-client-user-approval-controls.
2. Nothing validates sampling messages or results, either direction. sampleViaBroker unmarshals only maxTokens/systemPrompt; messages is never inspected — tool-result messages with non-tool_result content, or a tool_result id no earlier tool_use issued, pass through (register SMP-06 pairing). On return, the only checks are JSON-object / not-null (~L226-236); a missing role/model is then silently filled in ("unknown") instead of judged, and the result is never checked against its request (stopReason: "toolUse" / tool_use content against a tools-less request; era content shape per SMP-05). Client.answer validates nothing either. Gaps: sampling-both-validate-message-content (client + server rows).
3. Every sampling failure is -32603. The 2025-11-25 sampling error table assigns: user rejected → -1; tool result missing / tool results mixed with other content → -32602. mcpx produces neither: a decline becomes errors.New("the sampling request was " + action), an expired wait becomes the raw Await error, and Client.answer's handler wrap (internal/mcpclient/modern.go ~L296-303) flattens every handler error to -32603. An upstream cannot tell "the user said no" from "mcpx broke". Gap: sampling-client-errors-user-rejected-and-tool-shape.

Already in place (not this design's work)

• Denial: broker decline/cancel of a sampling question works and is tested (sampling-human-in-loop-can-deny).
• The broker substrate is shared and sufficient: sampling questions are ordinary broker rows (Mode: Sample), listed/shown/answered by the existing mcpx elicit commands — the review gap is rendering + routing, not a missing store or UI.
• Typed-error precedent exists (rpcError/codeInvalidParams in mcpclient; fault classification in mcpserver); the broker already refuses null Sample answers with the question left open.
• Neighbours are distinct: mcpx: design — sub-capability gating (gate on sampling.tools / sampling.context / elicitation.form, not parent presence) #1753 gates which sampling fields may cross (its Phase 2 adds a request-shape -32602 before the handler — this design's -32602s are content errors decided by validation, and compose with it); design(mcpx): JSON Schema validation of tool input and output — one validator at the client choke point #1481 is schema validation of tool/elicitation payloads; design(mcpx): elicitation broker hygiene — owner-only store, bounded retention, redacted events, review-first answering #1675 is broker storage hygiene + review-first elicitation; the sampling rate limit is nix#257's.

The design (decisions recorded in the doc)

• One choke point, one validator. All sampling validation lives in one helper used by the broker path (sampleViaBroker, in and out) — where legacy wire requests and modern input_required answers already converge — not copied into mcpclient/mcpserver separately.
• Errors first (Phase 1). Decline/cancel of a sampling answer → -1 ("user rejected", action named). Expiry/no-answerer stays -32603 with an explicit expired message — nobody chose, so it is not a rejection. Tool-shape violations → -32602 (raised by Phase 2's checks through Phase 1's typed error). Client.answer's wrap preserves a typed error's code.
• Validation judges, doesn't repair (Phase 2). Request side, on open: messages decode per era (content single before 2025-11-25, single-or-array from 2025-11-25); tool-result messages hold only tool_result blocks, each id paired with a preceding tool_use — violations get -32602 before a question opens. Result side, on answer: result must carry role and model and era-legal content, and toolUse/tool_use is valid only against a tools-carrying request — and the silent role/model fill-in is removed (it manufactures fields the answerer never supplied). A bad answer is refused at the broker step with the question left open where it arrived through the broker. Model-hint mismatch is not a failure (hints are expressly ignorable).
• Review on the existing surface (Phase 3). No new UI: mcpx elicit renders a Sample question as sampling (server, system prompt, message list; full JSON on show; a real CreateMessageResult answer skeleton instead of '{}'). Review-before-delivery takes the honest form this architecture has — inspect/override while pending, results recorded and visible via result — stated plainly in CLI help; a genuine pre-delivery staging hold for agent answers is an open question in the doc, not a phase.

Phases (sub-issues of this issue)

• Phase 1 — typed sampling errors (-1 rejection, -32602 tool-shape type, expiry stays -32603 labelled). Independent.
• Phase 2 — message + result validation at the broker (request pairing/era shape; result-vs-request; fill-in removed). Independent in code; its -32602 raising uses Phase 1's typed error (triage settles the seam if Phase 1 hasn't landed — not hard-gated).
• Phase 3 — reviewable sampling in mcpx elicit + conformance-matrix/register truth-up + nix#256 completion evidence. Gated on Phase 2.

Open questions (kept in the design doc, NOT filed)

• Genuine pre-delivery staging of agent sampling answers (a latency-contract change; only on evidence inspect-while-pending is insufficient).
• Era threading to the broker: if the upstream's era can't reach sampleViaBroker without new plumbing, union-shape acceptance vs plumbing for a deprecated feature is Phase 2 triage's recorded call.
• Whether a validated-bad request should also be recorded (count/log naming the server) for chronic-malformation visibility.
• Sampling as a client-hosted task (2025-11-25 only): untouched; would inherit the validator if it ever becomes real.

Acceptance (design level)

• Phases 1–3 landed. A person can read a pending sampling request's actual messages in mcpx elicit and answer with a well-formed skeleton; a malformed request is refused -32602 before any question opens; a malformed or request-mismatched result never reaches the upstream and missing role/model is refused, not filled; a decline reaches the upstream as -1 and an expiry as -32603 naming expiry.
• The seven scoped #256 conformance gaps retired or explicitly recorded partial in the matrix; mcpx: sampling relay -- human review, validation of results, error mapping (8 conformance rows) dezren39/darwin-nix#256 carries completion evidence against each acceptance bullet and is closed iff all are met.

Acceptance criteria

• Phases 1–3 (sub-issues of this design) have landed: typed sampling errors, broker message+result validation, and reviewable sampling in mcpx elicit with matrix/register truth-up.
• A declined sampling request reaches the upstream as -1; tool-shape violations as -32602; an expired wait as -32603 naming expiry — no sampling failure is flattened into an unlabelled internal error.
• Sampling requests are validated before a broker question opens (era content shape; tool-result pairing per SMP-06) and results are validated against their request before relay (role/model present, era-legal content, toolUse only against a tools-carrying request); the silent role/model fill-in is gone.
• mcpx elicit renders a Sample question's server, system prompt and messages, and offers a real CreateMessageResult answer skeleton.
• The seven scoped mcpx: sampling relay -- human review, validation of results, error mapping (8 conformance rows) dezren39/darwin-nix#256 conformance gaps are retired or explicitly recorded partial, and mcpx: sampling relay -- human review, validation of results, error mapping (8 conformance rows) dezren39/darwin-nix#256 carries completion evidence against each of its acceptance bullets, closed if and only if all are met.