allowed_tools=[] 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 allowed_tools:

if self._options.allowed_tools:  # line 195
    cmd.extend(["--allowedTools", ",".join(self._options.allowed_tools)])

Since [] is falsy in Python, passing allowed_tools=[] never sends --allowedTools to the CLI subprocess. The intent of allowed_tools=[] is "allow no tools from the base set", but it silently does nothing.

Expected Behavior

allowed_tools=[] should pass --allowedTools "" to the CLI, disabling all allowed tools (same behavior as tools=[] which correctly passes --tools "").

Comparison with tools handling

The tools field correctly uses an is not None check (line ~183):

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 allowed_tools and disallowed_tools both use truthiness checks, making empty lists indistinguishable from "not set".

Root Cause

The allowed_tools field defaults to field(default_factory=list) (always []), so a truthiness check can't distinguish "not set" from "explicitly empty". The fix requires either:

1. Changing the default to None and using is not None check, or
2. Using is not None check with the current default (would always pass --allowedTools "" — breaking change)

Same issue affects disallowed_tools

if self._options.disallowed_tools:  # line 204 — same truthiness bug
    cmd.extend(["--disallowedTools", ",".join(self._options.disallowed_tools)])

Workaround

Use tools=[] instead of allowed_tools=[] to disable all tools.

Versions

• claude-agent-sdk 0.1.45 (also present in 0.1.39)
• Python 3.14

[qing-ant]

Thanks for the detailed report — you've correctly identified the truthiness check, but after tracing this end-to-end, the underlying issue is that allowed_tools doesn't do what its name suggests.

allowed_tools maps to the CLI's --allowedTools flag, which controls permission pre-approval rules (e.g., allowed_tools=["Bash(git:*)"] means "don't prompt for permission when running git commands"). An empty allowlist means "no special pre-approvals" — which is semantically identical to not specifying it. Even if we passed --allowedTools "" to the CLI, parseToolListFromCLI in the CLI filters out empty strings, so the net effect is the same.

What you're looking for is the tools option:

• tools=[] → no tools available (what you want)
• tools=["Read", "Write"] → only these tools available
• tools=None (default) → all default tools

You already found this workaround — it's actually the correct API. We will look at updating the docs to be more clear on this.