fix: pass --setting-sources for empty list to disable filesystem settings (#822)

## Summary

`setting_sources=[]` was treated as falsy and silently dropped, so it
behaved the same as `None`: the spawned CLI loaded its default
user/project/local setting sources. The TypeScript SDK already
distinguishes `undefined` (CLI defaults) from `[]` (disable all) by
checking `!== undefined` and using equals-syntax so the empty value
survives argv parsing.

This change applies the same pattern: check `is not None` and pass
`--setting-sources=` (single argv element) so an empty list reaches the
CLI parser as "disable all sources."

## Tests

- `test_build_command_setting_sources_omitted_when_not_provided`: now
uses `startswith` so it can't pass vacuously against the equals form
- `test_build_command_setting_sources_empty_list_disables_all`:
rewritten; previously asserted the flag was omitted for `[]`
- `test_build_command_setting_sources_included_when_provided`: updated
for single-element `--setting-sources=user,project`

```
3 passed, 56 deselected
```

Companion docs change: anthropics/claude-code-docs branch
`claude/clarify-cost-tracking-docs-3ILH3`.

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: sarahdeaton

examples/setting_sources.py

@@ -10,12 +10,12 @@
 - "project": Project-level settings (.claude/ in project)
 - "local": Local gitignored settings (.claude-local/)
 
-IMPORTANT: When setting_sources is not provided (None), NO settings are loaded
-by default. This creates an isolated environment. To load settings, explicitly
-specify which sources to use.
+When setting_sources is not provided (None), the CLI loads its default
+sources: user, project, and local. Pass an empty list to disable all
+filesystem setting sources.
 
 By controlling which sources are loaded, you can:
-- Create isolated environments with no custom settings (default)
+- Disable filesystem settings with setting_sources=[]
 - Load only user settings, excluding project-specific configurations
 - Combine multiple sources as needed
 
@@ -45,17 +45,46 @@ def extract_slash_commands(msg: SystemMessage) -> list[str]:
 
 
 async def example_default():
-    """Default behavior - no settings loaded."""
+    """Default behavior: None loads CLI default sources (user, project, local)."""
     print("=== Default Behavior Example ===")
     print("Setting sources: None (default)")
-    print("Expected: No custom slash commands will be available\n")
+    print("Expected: project slash commands like /commit ARE available\n")
 
     sdk_dir = Path(__file__).parent.parent
 
     options = ClaudeAgentOptions(
         cwd=sdk_dir,
     )
 
+    async with ClaudeSDKClient(options=options) as client:
+        await client.query("What is 2 + 2?")
+
+        async for msg in client.receive_response():
+            if isinstance(msg, SystemMessage) and msg.subtype == "init":
+                commands = extract_slash_commands(msg)
+                print(f"Available slash commands: {commands}")
+                if "commit" in commands:
+                    print("✓ /commit is available (expected: CLI defaults loaded)")
+                else:
+                    print("❌ /commit is NOT available (unexpected)")
+                break
+
+    print()
+
+
+async def example_disable_all():
+    """Empty list disables all filesystem setting sources."""
+    print("=== Disable All Sources Example ===")
+    print("Setting sources: []")
+    print("Expected: no custom slash commands will be available\n")
+
+    sdk_dir = Path(__file__).parent.parent
+
+    options = ClaudeAgentOptions(
+        setting_sources=[],
+        cwd=sdk_dir,
+    )
+
     async with ClaudeSDKClient(options=options) as client:
         await client.query("What is 2 + 2?")
 
@@ -66,7 +95,7 @@ async def example_default():
                 if "commit" in commands:
                     print("❌ /commit is available (unexpected)")
                 else:
-                    print("✓ /commit is NOT available (expected - no settings loaded)")
+                    print("✓ /commit is NOT available (expected: sources disabled)")
                 break
 
     print()
@@ -139,6 +168,7 @@ async def main():
     """Run all examples or a specific example based on command line argument."""
     examples = {
         "default": example_default,
+        "disable_all": example_disable_all,
         "user_only": example_user_only,
         "project_and_user": example_project_and_user,
     }

src/claude_agent_sdk/_internal/transport/subprocess_cli.py

@@ -280,8 +280,8 @@ def _build_command(self) -> list[str]:
         # Agents are always sent via initialize request (matching TypeScript SDK)
         # No --agents CLI flag needed
 
-        if self._options.setting_sources:
-            cmd.extend(["--setting-sources", ",".join(self._options.setting_sources)])
+        if self._options.setting_sources is not None:
+            cmd.append(f"--setting-sources={','.join(self._options.setting_sources)}")
 
         # Add plugin directories
         if self._options.plugins:

tests/test_transport.py

@@ -434,16 +434,16 @@ def test_build_command_setting_sources_omitted_when_not_provided(self):
             options=make_options(),
         )
         cmd = transport._build_command()
-        assert "--setting-sources" not in cmd
+        assert not any(a.startswith("--setting-sources") for a in cmd)
 
-    def test_build_command_setting_sources_omitted_when_empty(self):
-        """Test that --setting-sources is omitted when setting_sources is empty list."""
+    def test_build_command_setting_sources_empty_list_disables_all(self):
+        """Test that setting_sources=[] passes --setting-sources= to disable all sources."""
         transport = SubprocessCLITransport(
             prompt="test",
             options=make_options(setting_sources=[]),
         )
         cmd = transport._build_command()
-        assert "--setting-sources" not in cmd
+        assert "--setting-sources=" in cmd
 
     def test_build_command_setting_sources_included_when_provided(self):
         """Test that --setting-sources is included when setting_sources has values."""
@@ -452,9 +452,7 @@ def test_build_command_setting_sources_included_when_provided(self):
             options=make_options(setting_sources=["user", "project"]),
         )
         cmd = transport._build_command()
-        assert "--setting-sources" in cmd
-        idx = cmd.index("--setting-sources")
-        assert cmd[idx + 1] == "user,project"
+        assert "--setting-sources=user,project" in cmd
 
     def test_build_command_with_extra_args(self):
         """Test building CLI command with extra_args for future flags."""