setting_sources=[] silently ignored due to truthiness check in _build_command

[joshwilhelmi]

Bug Description

In subprocess_cli.py, the _build_command method uses a truthiness check for setting_sources:

if self._options.setting_sources:  # line 283
    cmd.extend(["--setting-sources", ",".join(self._options.setting_sources)])

Since [] is falsy in Python, passing setting_sources=[] never sends --setting-sources to the CLI subprocess. The intent of setting_sources=[] is "load no setting sources", but it silently does nothing — the CLI falls back to loading all default sources.

Expected Behavior

setting_sources=[] should pass --setting-sources "" to the CLI, disabling all setting sources.

Comparison with tools handling

This is the same class of bug as #634 (allowed_tools=[]), which was fixed. The tools field correctly uses an is not None check:

if self._options.tools is not None:  # Correct: distinguishes None from []
    tools = self._options.tools
    if isinstance(tools, list):
        if len(tools) == 0:
            cmd.extend(["--tools", ""])

But setting_sources still uses a truthiness check, making an empty list indistinguishable from "not set".

Suggested Fix

if self._options.setting_sources is not None:
    if len(self._options.setting_sources) == 0:
        cmd.extend(["--setting-sources", ""])
    else:
        cmd.extend(["--setting-sources", ",".join(self._options.setting_sources)])

Workaround

Pass setting_sources=[""] (a list containing an empty string) to force the flag through the truthiness check. This produces --setting-sources "" which the CLI interprets as no sources.

Versions

• claude-agent-sdk 0.1.45
• Python 3.14

[Hor1zonZzz]

The suggested workaround setting_sources=[""] does not actually work.

I tested the CLI directly:

--setting-sources value	Result
"" (empty string)	Silently ignored — CLI falls back to loading all sources (user + project + local)
"none"	CLI rejects with error: Invalid setting source: none. Valid options are: user, project, local
"project"	Works — only loads project-level settings, user-level plugins/skills are excluded
"user"	Loads all user-level plugins/skills

The core issue is twofold:

1. SDK bug: setting_sources=[] is falsy, so the --setting-sources flag is never passed to the CLI (as described in this issue).
2. CLI bug: Even when --setting-sources "" reaches the CLI, it silently ignores the empty string and falls back to default behavior (load all sources) instead of treating it as "load nothing".

There is currently no way to fully isolate an SDK application from all filesystem settings. The closest workaround is setting_sources=["project"], which at least excludes user-level config (~/.claude/), but still loads .claude/settings.json if present.

Tested on:

• claude-agent-sdk==0.1.56
• Claude Code CLI v2.x
• Python 3.12 / macOS

[himynameisben]

Workaround setting_sources=[""] confirmed working

setting_sources=[""] successfully excludes all user-level skills from ~/.claude/skills/ (38 custom skills in my case). Only the ~6 CLI built-in skills (update-config, keybindings-help, simplify, loop, schedule, claude-api) remain, which are hardcoded in the binary and unaffected by setting_sources.

This contradicts @Hor1zonZzz's earlier report that the workaround doesn't work — it may depend on CLI version.

• claude-agent-sdk==0.1.58
• Claude Code CLI 2.1.100
• macOS 15.7.5 / arm64 / Python 3.14