chore(client): deprecate client-side compaction helpers

* deprecate: mark client-side compaction helpers as deprecated

Server-side compaction via `edits=[{"type": "compact_20260112"}]` is now
the recommended approach. Adds DeprecationWarning when compaction_control
is enabled and @deprecated docstrings.

* chore: remove auto_compaction example

The example demonstrated client-side compaction which is now deprecated
in favor of server-side compaction.

* chore: align deprecation message wording

Use "in a future version" and "in the params passed to tool_runner()"
to match TypeScript SDK phrasing.

Author: dtmeadows

examples/auto_compaction.py

@@ -29,6 +29,13 @@
 
 
 class CompactionControl(TypedDict, total=False):
+    """Client-side compaction control configuration.
+
+    .. deprecated::
+        Use server-side compaction instead by passing
+        ``edits=[{"type": "compact_20260112"}]`` in the params passed to ``tool_runner()``.
+        See https://platform.claude.com/docs/en/build-with-claude/compaction
+    """
     context_token_threshold: int
     """The context token threshold at which to trigger compaction.
 

src/anthropic/lib/tools/_beta_compaction_control.py

@@ -146,6 +146,15 @@ def __init__(
         )
         self._client = client
 
+        if compaction_control is not None and compaction_control.get("enabled"):
+            warnings.warn(
+                "The 'compaction_control' parameter is deprecated and will be removed in a future version. "
+                "Use server-side compaction instead by passing `edits=[{'type': 'compact_20260112'}]` in your "
+                "the params passed to `tool_runner()`. See https://platform.claude.com/docs/en/build-with-claude/compaction",
+                DeprecationWarning,
+                stacklevel=3,
+            )
+
         self._iterator = self.__run__()
         self._last_message: (
             Callable[[], ParsedBetaMessage[ResponseFormatT]] | ParsedBetaMessage[ResponseFormatT] | None
@@ -416,6 +425,15 @@ def __init__(
         )
         self._client = client
 
+        if compaction_control is not None and compaction_control.get("enabled"):
+            warnings.warn(
+                "The 'compaction_control' parameter is deprecated and will be removed in a future version. "
+                "Use server-side compaction instead by passing `edits=[{'type': 'compact_20260112'}]` in your "
+                "the params passed to `tool_runner()`. See https://platform.claude.com/docs/en/build-with-claude/compaction",
+                DeprecationWarning,
+                stacklevel=3,
+            )
+
         self._iterator = self.__run__()
         self._last_message: (
             Callable[[], Coroutine[None, None, ParsedBetaMessage[ResponseFormatT]]]

src/anthropic/lib/tools/_beta_runner.py

@@ -473,24 +473,25 @@ def submit_analysis(summary: str) -> str:  # noqa: ARG001
             """Call this LAST with your final analysis."""
             return "Analysis submitted"
 
-        runner = snapshot_client.beta.messages.tool_runner(
-            model="claude-sonnet-4-5",
-            max_tokens=4000,
-            tools=[submit_analysis],
-            messages=[
-                {
-                    "role": "user",
-                    "content": (
-                        "Write a detailed 500 word essay about dogs, cats, and birds. "
-                        "Call the tool submit_analysis with the information about all three animals. "
-                        "Note that you should call it only once at the end of your essay."
-                    ),
-                }
-            ],
-            betas=["structured-outputs-2025-12-15"],
-            compaction_control={"enabled": True, "context_token_threshold": 500},
-            max_iterations=1,
-        )
+        with pytest.warns(DeprecationWarning, match="compaction_control.*deprecated"):
+            runner = snapshot_client.beta.messages.tool_runner(
+                model="claude-sonnet-4-5",
+                max_tokens=4000,
+                tools=[submit_analysis],
+                messages=[
+                    {
+                        "role": "user",
+                        "content": (
+                            "Write a detailed 500 word essay about dogs, cats, and birds. "
+                            "Call the tool submit_analysis with the information about all three animals. "
+                            "Note that you should call it only once at the end of your essay."
+                        ),
+                    }
+                ],
+                betas=["structured-outputs-2025-12-15"],
+                compaction_control={"enabled": True, "context_token_threshold": 500},
+                max_iterations=1,
+            )
 
         with caplog.at_level(logging.INFO, logger="anthropic.lib.tools._beta_runner"):
             next(runner)