Bug: @filepath syntax not supported, agents silently dropped

[peterjrichens]

Bug: @filepath syntax not supported, agents silently dropped

Summary

PR #245 introduced a workaround for command line length limits by using --agents @/tmp/file.json syntax. However, the Claude CLI does not support @filepath syntax, causing agents to be silently dropped when command lines exceed 100KB (macOS/Linux) or 8KB (Windows).

Note: While PR #245 was intended to fix Windows-specific command line limits, this bug now affects all platforms (Windows, macOS, Linux) because the @filepath syntax is not implemented in the CLI on any platform.

Reproduction

# Works: Inline JSON
claude --output-format stream-json --verbose --print "hi" --max-turns 1 \
  --agents '{"test-agent": {"description": "test", "prompt": "test"}}' 2>&1 | \
  jq -r 'select(.type == "system" and .subtype == "init") | .agents[]' | grep test-agent
# Output: test-agent ✅

# Fails: @filepath notation
echo '{"test-agent": {"description": "test", "prompt": "test"}}' > /tmp/test.json
claude --output-format stream-json --verbose --print "hi" --max-turns 1 \
  --agents "@/tmp/test.json" 2>&1 | \
  jq -r 'select(.type == "system" and .subtype == "init") | .agents[]' | grep test-agent
# Output: (nothing) ❌

Root Cause

Location: claude_agent_sdk/_internal/transport/subprocess_cli.py:248

cmd[agents_idx + 1] = f"@{temp_file.name}"  # CLI doesn't support @ syntax

The SDK assumes the CLI supports @filepath syntax, but it doesn't. The CLI tries to parse @/tmp/file.json as literal JSON, fails silently, and loads zero agents.

Introduced in: https://github.com/anthropics/claude-agent-sdk-python/pull/245/files

[smithla02]

@ashwin-ant @ollie-anthropic hello 👋 . We are still seeing this issue on our side, the Reproduction section from the original issue still fails and the section of the code that uses the @filepath syntax was never changed.

Can we please reopen this issue? And is it possible to make a plan to address this?

Thank you!