Verifying the build scripts

The SDK itself is a library (drive it through import claude_agent_sdk), but the scripts/ directory is a set of CLIs run by the release workflows. Verify them by running them, not by importing them.

NEVER run the real installer

scripts/download_cli.py shells out to curl https://claude.ai/install.sh | bash (and the PowerShell equivalent). Running it for real overwrites the claude binary on the developer's machine. Do not run bash install.sh, and do not invoke download_cli.py with latest/stable (or any case variant) against the real network.

Instead, put stub curl / bash / powershell on a temp PATH and drive the script under env -i with an isolated HOME (so find_installed_cli() cannot discover the real binary and copy it into src/claude_agent_sdk/_bundled/).

The harness

SB=$(mktemp -d); mkdir -p $SB/stub $SB/home $SB/repo/src/claude_agent_sdk
cp scripts/{download_cli.py,build_wheel.py,update_cli_version.py,_cli_version_validation.py} $SB/repo/scripts/
printf '__cli_version__ = "2.1.208"\n' > $SB/repo/src/claude_agent_sdk/_cli_version.py

cat > $SB/stub/curl <<'EOF'
#!/bin/bash
out=""; prev=""; for a in "$@"; do [ "$prev" = "-o" ] && out="$a"; prev="$a"; done
echo "[stub curl] argv: $*" >> "$MARKER"
[ -n "$out" ] && printf '%b' "${CURL_BODY:-#!/bin/bash\necho hi\n}" > "$out"
exit ${CURL_EXIT:-0}
EOF
cat > $SB/stub/bash <<'EOF'
#!/bin/bash
{ echo "[stub bash] argc=$#"; for a in "$@"; do echo "    <$a>"; done; } >> "$MARKER"
EOF
chmod +x $SB/stub/*

cd $SB/repo
env -i HOME=$SB/home PATH=$SB/stub:/usr/bin:/bin MARKER=$SB/m \
    CLAUDE_CLI_VERSION=2.1.208 .venv/bin/python scripts/download_cli.py

run_command() captures the child's output, so the stubs must log to a $MARKER file — printing to stderr is swallowed.

Flows worth driving

• update_cli_version.py <version> — the whole validator surface is reachable here: a concrete version writes the file; latest/stable, v2.1.207, next, 2.1, and a quote-breakout string each exit 1 with a distinct message and leave the file untouched.
• build_wheel.py --skip-sdist — reads the pin, then chains into download_cli.py. Rewrite _cli_version.py in the sandbox to a moving tag / single quotes / garbage / delete it: each must fail before any subprocess is spawned. --cli-version <v> bypasses the pin (intentional escape hatch; the release workflow does not use it).
• download_cli.py — set CURL_BODY to an HTML error page or an empty string to prove the body check refuses it with no retry; empty the PATH to prove a missing curl fails fast in one attempt; CURL_EXIT=22 to prove a genuine transient failure still retries 3×.
• The Windows path is unreachable on Linux. It is behind platform.system() == "Windows". Drive it with a small runner that patch.object(m.platform, "system", return_value="Windows") and a stub powershell that reads the -Command text and honours $env:CLAUDE_CLI_INSTALL_SCRIPT. This is the one place where forcing the platform is legitimate.

Gotchas

• ${CURL_BODY:-default} treats an empty body as unset. Use a separate stub that does : > "$out" to test the empty-body branch.
• The retry path really sleeps (jitter up to 5s, then 2s + 4s). A full three-attempt run takes ~10s; budget for it rather than assuming a hang.