@filepath syntax for --agents not supported by CLI

[karlolukic]

Description

When the total command line exceeds 100KB, the SDK writes the agents JSON to a temp file and passes --agents @/path/to/temp.json. However, the CLI doesn't parse this syntax - it treats the literal string @/path/... as the JSON value, which fails to parse.

Reproduction Steps

1. Create agent definitions totaling >60KB
2. Add a system prompt >40KB
3. Total command exceeds 100KB limit
4. SDK writes to temp file (visible in logs: "Using temp file for --agents")
5. CLI fails to load custom agents

Expected Behavior

CLI should read JSON from the file path when --agents value starts with @

Actual Behavior

CLI sees literal @/path/... string, can't parse as JSON, loads zero custom agents.

Error observed by orchestrator:

Agent type 'file-processor' not found. Available agents: general-purpose, statusline-setup, Explore, Plan

Versions

• SDK: 0.1.8
• CLI: 2.1.12

Workaround

Keep total command under 100KB by reducing prompt sizes.

[karlolukic]

Closing - filed prematurely without proper investigation. Will reopen with verified reproduction if the issue is confirmed.

[0xeb]

I still face this.

Did you solve it? @karlolukic

[karlolukic]

@0xeb Yes, I did solve it with a workaround. The CLI doesn't support the @filepath syntax for --agents.

The fix: "Monkey-patch" the SDK to increase the command line limit so it never triggers the temp file fallback:

import claude_agent_sdk._internal.transport.subprocess_cli as _subprocess_cli
_subprocess_cli._CMD_LENGTH_LIMIT = 500000  # Increase from 100k to 500k

Placed that after imports, before creating any agents.

Why it works: macOS supports ~1MB command lines (getconf ARG_MAX = 1048576), so 500k is safe. This prevents the SDK from falling back to the broken @filepath mechanism.

I closed this issue prematurely because I thought I might have misdiagnosed it, but your confirmation in #501 validates that it seems to be a real bug.

[0xeb]

Not a good solution. Especially so for Windows.