[Schema][Server] feat: support sampling with tools

[wWzZb]

What

• Add tools and toolChoice to sampling requests and wire them through ClientGateway::sample().
• Add sampling tool-use and tool-result content blocks, array content support, message metadata, and standard stop-reason values with open-string compatibility.
• Expose sampling.context and sampling.tools client capabilities.
• Add round-trip and validation coverage for the new schema types.

Why

The SDK did not yet model the SEP-1577 protocol additions, so servers could not express tool-enabled sampling loops through the typed API.

Impact

Existing single-content sampling calls remain supported. The new constructor parameters are optional and appended to preserve current call sites.

Checks

• make cs
• make phpstan
• make tests — 938 tests, 2786 assertions, 7 existing skips
• make docs

Closes #155

[chr-hertel]

Thanks @wWzZb for working on this - please extend the CHANGELOG.md for upcomgin release 0.8.0, extend docs and example where meaningful and double-check if there's still missing unit tests here and there - i at least caught one place where i think it makes sense to add some.

Thanks again, great addition for feature parity with the spec! 👍

[chr-hertel]

if we adopt the enum here, we can basically drop string, right?

Suggested change

	public readonly SamplingStopReason|string|null $stopReason = null,
	public readonly ?SamplingStopReason $stopReason = null,

[wWzZb]

I kept the string arm intentionally. The current MCP schema defines stopReason as an open string so clients can return provider-specific reasons, while SamplingStopReason documents the standard values. fromArray() now maps known values to the enum and preserves unknown values; the provider-specific path is covered by a unit test. See https://modelcontextprotocol.io/specification/2025-11-25/schema#create-message-result.

[wWzZb]

Addressed the review feedback in 991fe4f:

• added the sampling content PHPStan alias;
• covered both array- and object-form sampling capability hydration;
• added the upcoming 0.8.0 changelog entry;
• documented tool-enabled sampling with a callback example;
• strengthened the provider-specific stopReason round-trip test.

I kept SamplingStopReason|string|null because the MCP schema explicitly defines stopReason as an open string for provider-specific values, and replied with the spec reference in that thread.

Local checks: make cs, make phpstan, make tests (937 tests, 2785 assertions, 7 skips), and make docs.

[wWzZb]

Follow-up spec audit in 0b1cb6d:

• tightened ToolResultContent so its constructor only accepts standard tool-result content blocks;
• added regression coverage for rejecting non-standard nested message content;
• updated the server-side sampling guide to the 2025-11-25 specification and documented tools, toolChoice, and the capability requirements;
• documented the soft-deprecation rules for includeContext.

Checks: make cs, make phpstan, make tests (938 tests, 2786 assertions, 7 skips), and make docs.