Classify Modern mid-call capability refusals per spec

[JAORMX]

Summary

Why. When a backend tool demands mid-call elicitation or sampling during a Modern (2026-07-28) client's tools/call, there is no downstream session to forward it to (the revision removed server-initiated requests), and today the failure surfaces as an opaque -32603 echoing the backend's raw error chain — including the backend workload ID, contradicting writeModernListError's leak policy in the same file. The draft schema defines the honest answer for the common case: MissingRequiredClientCapabilityError (-32021, data.requiredCapabilities), which a client can act on where -32603 is opaque.

The key insight that shapes the design (and why this is not just an error-code swap): the refusal evidence cannot ride the error chain. The typed refusal — mcpcompat's server.ErrNoActiveSession, raised inside vMCP's own sdkElicitationAdapter/sdkSamplingAdapter — is the answer to the backend's elicitation request; the backend then fails its own tool, and what the dispatcher receives back over the wire is a flattened string. So classification uses an in-process capabilityRefusalRecorder written at the exact point of refusal and read after a failed call.

The contract (writeModernCallFailure), two paths:

• Capability NOT declared in the request's _meta clientCapabilities → -32021 with data.requiredCapabilities typed as a ClientCapabilities object ({"elicitation":{}}, matching the spec's example), and a message naming both the capability and the gateway limitation — so a caller that reacts to -32021 by declaring the capability on a retry learns immediately that doing so won't help here.
• Capability DECLARED → deliberately NOT -32021 (the client did declare it; blaming it would be wrong). The spec's answer for this case is MRTR input_required (SEP-2322), which vMCP deliberately does not implement, and the eight-code 2026-07-28 vocabulary has no "operation not supported" alternative — a documented spec gap. It stays -32603 with a vMCP-owned message naming multi-round retrieval as the cause.

Both messages are crafted by vMCP, closing the workload-ID leak on this path (asserted by NotContains in the new test).

The two things a reviewer must weigh

1. The -32021 is served at HTTP 200 — a deliberate, documented deviation from the spec-mandated 400. SEP-2575:391-396 MUSTs 400 (execution-time language; go-sdk's own doc comment on the error type tells handlers to return it mid-execution, so the timing is sanctioned). But go-sdk's streamable client (v1.7.0-pre.3) treats any non-transient 4xx as a connection failure: isTransientHTTPStatus covers only 500/502/503/504/429, so a 400 falls through checkResponse to fail(), which closes the session permanently — one refused elicitation would kill every subsequent request on the client. The JSON-RPC body stays fully conformant (what a non-go-sdk client parses); only the transport status deviates. Tracked upstream as go-sdk#1117; the comment on writeModernMissingCapability says to revisit the 200 when it's fixed. mcpparser.WriteClassificationError is deliberately NOT reused — it hard-codes 400, correctly for its other callers.

2. The context-carried recorder, versus vmcp-anti-patterns #1. The rule targets domain data flowing invisibly between middleware. This is a transport-boundary observation channel written by a lower layer, mirroring the audit.BackendInfoFromContext pattern these same dispatch verbs already use. The crux of why nothing else can carry it: MultiSession cannot — its absence is the very thing being recorded — and the requesters are bound once at startup (BindForwarders), so a per-call parameter cannot reach them. Disagree on the merits here if you disagree; the reasoning is in modern_capability_refusal.go's type comment.

One subtlety worth review attention: a client decline must NOT record a refusal — a user's "no" is not a capability gap — so the adapters record only on errors.Is(err, server.ErrNoActiveSession), and the unit tests pin that distinction explicitly.

Provenance and relationship to #6051

This work was split out of #6051 after review: that PR's security approval was based on it being test-and-docs only, so the production change moved here for its own review (which is why the work predates the PR). References #5959, #6033, #5743. It completes the honest-negotiation contract whose analysis lives in docs/arch/10-virtual-mcp-architecture.md (added by #6051), and it delivers the "vMCP-owned message with our own surface to assert on" that the #6051 review asked for.

Landing-order note (either order works):

• Whoever lands second updates the arch doc's "Until that lands, both cases surface as -32603" sentence to present tense (that paragraph, added by Make forwarding tests' Legacy dependency explicit #6051, already documents this PR's contract including the 200 deviation).
• The postModern capability-preservation hunk overlaps Make forwarding tests' Legacy dependency explicit #6051's near-identically — trivial rebase resolution.
• Make forwarding tests' Legacy dependency explicit #6051's ElicitingToolFailsCleanly deliberately asserts nothing about the message text, pointing here; no assertion flip is needed in either order.

Type of change

• Bug fix
• New feature
• Refactoring (no behavior change)
• Dependency update
• Documentation
• Other (describe):

Test plan

• Unit tests (task test scope: full pkg/vmcp/server package green, 94.7s; new unit tests for the declared-capability helper, the recorder, and both adapters' record-only-on-ErrNoActiveSession behavior including the decline case)
• Linting (task lint) — 0 issues; go vet ./... run separately, clean
• Manual testing (describe below)

Manual verification:

1. Mutation A — modernClientDeclaredCapability mutated to always-true: exactly the 2 undeclared subtests of TestIntegration_Modern_RealBackend_MidCallCapabilityContract fail (they get -32603 instead of -32021); declared subtests pass. Restored: 4/4 pass.
2. Mutation B — the refusal block in writeModernCallFailure skipped: all 4 subtests fail (no crafted message, wrong code, leak assertions trip). Restored: 4/4 pass.
3. Legacy behavior byte-identical: the recorder is installed only by the Modern dispatch verbs; on the Legacy/SDK path no recorder exists and the adapters' recording is a no-op. Full package (including all Legacy forwarding tests) green.

Does this introduce a user-facing change?

Yes: Modern (2026-07-28) clients calling a tool that requires mid-call elicitation/sampling now receive an actionable -32021 MissingRequiredClientCapability error (with data.requiredCapabilities) when they did not declare the capability, and a clear -32603 naming multi-round retrieval (SEP-2322) as the unimplemented mechanism when they did — instead of an opaque internal error echoing backend internals.

Special notes for reviewers

• SEP-2322 (MRTR) itself remains deliberately unimplemented; the user-approved deferral analysis is in the arch doc (Make forwarding tests' Legacy dependency explicit #6051). This PR is the honest error surface for the gap, not the gap's fix.
• TestForwarding_Progress_RealBackend has a known lost-notification flake under CI -race load (best-effort drain barrier, see Flaky: TestForwarding_*_RealBackend time out waiting for forwarded notifications under CI load #5962 lineage) — unrelated to this diff.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GvBj7nNWqDQ3rKYNeY6aam

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 72.21%. Comparing base (a099fa0) to head (71f61a6).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6061      +/-   ##
==========================================
+ Coverage   72.20%   72.21%   +0.01%     
==========================================
  Files         721      722       +1     
  Lines       75062    75138      +76     
==========================================
+ Hits        54198    54262      +64     
- Misses      17003    17013      +10     
- Partials     3861     3863       +2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[ChrisJBurns]

/retest

[ChrisJBurns]

/retest

[amirejaz]

Approving — this is high-quality, unusually well-documented work with solid test coverage (mutation testing, the leak NotContains assertion, and the decline-vs-refusal distinction all pinned explicitly). Nothing here is a blocker. A couple of non-blocking observations for the record:

1. The load-bearing invariant is context propagation. The whole mechanism hinges on the ctx carrying the recorder flowing unbroken from dispatchModern* → core.CallTool → backend client → sdkElicitationAdapter.RequestElicitation. That's not provable from the diff alone, but TestIntegration_Modern_RealBackend_MidCallCapabilityContract + Mutation B is exactly the right guardian for it. Worth making sure that integration test can't be silently t.Skip-ed in CI, since it's the thing standing between this and a regression.

2. Refusal→failure is a heuristic, not proven causation (minor). writeModernCallFailure attributes any non-authz call error to the recorded refusal. If a backend requested elicitation (refused + recorded), then recovered and later failed for an unrelated reason, the client would get capability-flavored messaging for an unrelated failure. Realistically the refusal is what fails the tool, so this is an acceptable trade-off — I'd just soften the doc comment to acknowledge it's the common-case attribution rather than certain causation.

3. (nit) Message wording duplication. The declared-capability -32603 message built inline in writeModernCallFailure restates most of writeModernMissingCapability's SEP-2322 wording; a shared message helper would keep them from drifting over time.

The HTTP 200-on-a-MUST-400 deviation is well justified (go-sdk would treat a 400 as permanent connection death) and already tracked as go-sdk#1117 with a documented revisit trigger — comfortable with it as-is.