From a10ea6172af63e9e41025794ba77a6580fbe67f0 Mon Sep 17 00:00:00 2001
From: Mng <50384638+Mng-dev-ai@users.noreply.github.com>
Date: Sun, 15 Mar 2026 09:06:51 +0200
Subject: [PATCH] feat: add worktree option to ClaudeAgentOptions

Support the --worktree CLI flag for creating git worktrees per session.
Accepts True for auto-generated names or a string for explicit naming.
---
 .../_internal/transport/subprocess_cli.py     |  7 ++++++
 src/claude_agent_sdk/types.py                 |  4 ++++
 tests/test_transport.py                       | 23 +++++++++++++++++++
 3 files changed, 34 insertions(+)

diff --git a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
index 1f0aac585..75d49974a 100644
--- a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
+++ b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
@@ -326,6 +326,13 @@ def _build_command(self) -> list[str]:
             if schema is not None:
                 cmd.extend(["--json-schema", json.dumps(schema)])
 
+        # Worktree support
+        if self._options.worktree is not None:
+            if isinstance(self._options.worktree, str):
+                cmd.extend(["--worktree", self._options.worktree])
+            elif self._options.worktree:
+                cmd.append("--worktree")
+
         # Always use streaming mode with stdin (matching TypeScript SDK)
         # This allows agents and other large configs to be sent via initialize request
         cmd.extend(["--input-format", "stream-json"])
diff --git a/src/claude_agent_sdk/types.py b/src/claude_agent_sdk/types.py
index 0fb615833..7610eb9f4 100644
--- a/src/claude_agent_sdk/types.py
+++ b/src/claude_agent_sdk/types.py
@@ -1096,6 +1096,10 @@ class ClaudeAgentOptions:
     # When enabled, files can be rewound to their state at any user message
     # using `ClaudeSDKClient.rewind_files()`.
     enable_file_checkpointing: bool = False
+    # Create a new git worktree for this session.
+    # When True, creates a worktree with an auto-generated name.
+    # When a string, creates a worktree with the specified name.
+    worktree: bool | str | None = None
 
 
 # SDK Control Protocol
diff --git a/tests/test_transport.py b/tests/test_transport.py
index 65e6ada71..e914aadcc 100644
--- a/tests/test_transport.py
+++ b/tests/test_transport.py
@@ -912,3 +912,26 @@ def test_build_command_large_agents_work(self):
         # No @filepath references should exist
         cmd_str = " ".join(cmd)
         assert "@" not in cmd_str
+
+    def test_build_command_with_worktree_bool(self):
+        """Test building CLI command with worktree=True."""
+        transport = SubprocessCLITransport(
+            prompt="test",
+            options=make_options(worktree=True),
+        )
+        cmd = transport._build_command()
+        assert "--worktree" in cmd
+        # Should not have a name argument after --worktree
+        wt_idx = cmd.index("--worktree")
+        assert wt_idx + 1 >= len(cmd) or cmd[wt_idx + 1].startswith("--")
+
+    def test_build_command_with_worktree_name(self):
+        """Test building CLI command with worktree as a named string."""
+        transport = SubprocessCLITransport(
+            prompt="test",
+            options=make_options(worktree="my-feature"),
+        )
+        cmd = transport._build_command()
+        assert "--worktree" in cmd
+        wt_idx = cmd.index("--worktree")
+        assert cmd[wt_idx + 1] == "my-feature"