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.

Author: Mng-dev-ai

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"])

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

tests/test_transport.py

@@ -912,3 +912,27 @@ 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"
+