SDK @filepath syntax for --agents flag doesn't work on Windows

Summary

When the Claude Agent SDK passes large agent definitions via the --agents CLI flag on Windows, it exceeds the 8000 character command line limit and falls back to writing the JSON to a temp file using @filepath syntax. However, the CLI doesn't parse this syntax correctly on Windows - it treats @filepath as a literal string instead of reading the file.

Environment

• OS: Windows
• Claude Code version: 2.1.22
• Claude Agent SDK version: 0.1.24

Steps to Reproduce

1. Create a test agents JSON file:

echo '{"test": {"description": "Test agent", "prompt": "Say hello"}}' > C:\temp\test_agents.json

1. Test with direct JSON (works):

claude --agents '{"test": {"description": "Test agent", "prompt": "Say hello"}}' --print "List agents" --max-turns 1

1. Test with @filepath (fails):

claude --agents "@C:\temp\test_agents.json" --print "List agents" --max-turns 1

Expected Behavior

The CLI should parse @filepath and read the agents JSON from the specified file, same as it does for other flags that support this syntax.

Actual Behavior

Custom agents defined in the file are not registered. The Task tool only shows built-in agents:

[Error] Agent type 'test' not found. Available agents: Bash, general-purpose, statusline-setup, Explore, Plan

Root Cause Analysis

The SDK's subprocess_cli.py has logic to handle Windows command line length limits:

# Line 37
_CMD_LENGTH_LIMIT = 8000 if platform.system() == "Windows" else 100000

# Lines 338-357
if len(cmd_str) > _CMD_LENGTH_LIMIT and self._options.agents:
    # Write to temp file and use @filepath
    cmd[agents_idx + 1] = f"@{temp_file.name}"

This assumes the CLI supports @filepath for --agents, but it doesn't appear to work on Windows.

Impact

• Any SDK application with agent definitions > 8000 chars fails on Windows
• This affects multi-agent orchestration patterns where agents have detailed prompts
• macOS/Linux are unaffected (100,000 char limit rarely exceeded)

Workaround

We implemented a "self-loading prompts" pattern where agents receive minimal prompts that instruct them to read full instructions from files at runtime. This keeps the JSON under 8000 chars.

Suggested Fix

Either:

1. Add proper @filepath parsing for the --agents flag on all platforms
2. Use an alternative mechanism for large agent definitions (environment variable, config file, etc.)
3. Document the Windows limitation if @filepath isn't intended to work with --agents