feat(types): widen SdkBeta to accept arbitrary anthropic-beta values

src/claude_agent_sdk/types.py

@@ -26,7 +26,12 @@
 ]
 
 # SDK Beta features - see https://docs.anthropic.com/en/api/beta-headers
-SdkBeta = Literal["context-1m-2025-08-07"]
+#
+# The known literal values surface in IDE autocomplete; the trailing ``str``
+# keeps the alias open so callers can opt into beta features that ship only
+# as ``anthropic-beta`` header values (e.g. ``token-efficient-tools-2025-02-19``)
+# without waiting on the SDK to enumerate them.
+SdkBeta = Literal["context-1m-2025-08-07"] | str
 
 # Agent definitions
 SettingSource = Literal["user", "project", "local"]
@@ -1543,10 +1548,18 @@ class ClaudeAgentOptions:
     betas: list[SdkBeta] = field(default_factory=list)
     """Enable beta features.
 
-    Currently supported:
+    Each entry is forwarded to the CLI via ``--betas`` and ultimately ends up
+    in the ``anthropic-beta`` request header. Known values surface in editor
+    autocomplete; arbitrary strings are also accepted so callers can opt into
+    new beta features without waiting on a SDK release.
+
+    Currently surfaced as a known literal:
 
     - ``"context-1m-2025-08-07"`` — Enable 1M token context window (Sonnet 4/4.5 only).
 
+    Other beta header values that ship from the API (for example
+    ``"token-efficient-tools-2025-02-19"``) may be passed through directly.
+
     See https://docs.anthropic.com/en/api/beta-headers.
     """
 

tests/test_transport.py

@@ -186,6 +186,42 @@ def test_build_command_with_dont_ask_permission_mode(self):
         assert "--permission-mode" in cmd
         assert "dontAsk" in cmd
 
+    def test_build_command_forwards_known_beta(self):
+        """Known SdkBeta literals reach ``--betas``."""
+        transport = SubprocessCLITransport(
+            prompt="test",
+            options=make_options(betas=["context-1m-2025-08-07"]),
+        )
+
+        cmd = transport._build_command()
+        assert "--betas" in cmd
+        assert cmd[cmd.index("--betas") + 1] == "context-1m-2025-08-07"
+
+    def test_build_command_forwards_arbitrary_beta(self):
+        """Arbitrary beta strings flow through unchanged.
+
+        Regression for #845: ``SdkBeta`` was previously a closed
+        ``Literal["context-1m-2025-08-07"]`` so callers could not opt
+        into header-only betas like ``token-efficient-tools-2025-02-19``
+        without bypassing the type. The alias was widened to also accept
+        ``str``; this guards the wire-level pass-through that users rely on.
+        """
+        transport = SubprocessCLITransport(
+            prompt="test",
+            options=make_options(
+                betas=[
+                    "context-1m-2025-08-07",
+                    "token-efficient-tools-2025-02-19",
+                ]
+            ),
+        )
+
+        cmd = transport._build_command()
+        assert "--betas" in cmd
+        assert cmd[cmd.index("--betas") + 1] == (
+            "context-1m-2025-08-07,token-efficient-tools-2025-02-19"
+        )
+
     def test_build_command_with_fallback_model(self):
         """Test building CLI command with fallback_model option."""
         transport = SubprocessCLITransport(