ANTHROPIC_LOG=debug corrupts SDK protocol - debug logs should go to stderr

[ragnorc]

ANTHROPIC_LOG=debug corrupts SDK protocol - debug logs should go to stderr

Problem

Setting ANTHROPIC_LOG=debug breaks the SDK. Debug logs are written to stdout, corrupting the JSON protocol used for parent-child communication.

const result = query({
  prompt: "Hello",
  options: {
    env: { ...process.env, ANTHROPIC_LOG: "debug" },
  },
});
// Error: CLI output was not valid JSON. Output: [log_71a72b] sending request {

This prevents users from debugging API-level issues (auth failures, rate limits, request/response inspection) when using the SDK.

Root Cause

Agent SDK (parent) ←── stdout ──← CLI (child)
                         ↑
         Protocol JSON   +   Anthropic SDK debug logs
         (expected)          (unexpected, breaks parsing)

The Anthropic HTTP client uses console.log for debug output → stdout. The SDK expects stdout to contain only protocol JSON.

Suggested Fix

Configure the Anthropic client inside the CLI to use stderr for logging:

const client = new Anthropic({
  logger: {
    debug: (msg) => process.stderr.write(`[debug] ${msg}\n`),
    info: (msg) => process.stderr.write(`[info] ${msg}\n`),
    warn: (msg) => process.stderr.write(`[warn] ${msg}\n`),
    error: (msg) => process.stderr.write(`[error] ${msg}\n`),
  },
});

This preserves stdout for protocol communication while routing debug output to stderr, where the SDK already captures it via the stderr callback.

Why This Matters

When things go wrong (auth issues, rate limits, timeouts), ANTHROPIC_LOG=debug is the standard way to diagnose problems with the Anthropic API. Having this broken in the Agent SDK makes debugging significantly harder. Users expect environment variables that work with the base SDK to also work here.

Workaround

We're currently using spawnClaudeCodeProcess to intercept stdout and filter non-JSON lines to stderr. Happy to share the implementation if helpful, but this should be unnecessary - debug logs belong on stderr.

Environment

• @anthropic-ai/claude-agent-sdk: 0.2.23
• Node.js: v24.3.0