Feature request: --agents-file flag to read agents JSON from a file

Summary

Add an --agents-file <path> CLI flag that reads agent definitions from a JSON file, analogous to the existing --system-prompt-file / --append-system-prompt-file flags.

Motivation

Tools that orchestrate Claude Code (e.g. iloom) pass large agent definitions via the --agents flag. When the JSON payload exceeds ~128 KB, it hits the Linux kernel's per-argument size limit (MAX_ARG_STRLEN, typically PAGE_SIZE * 32) and the exec syscall fails with E2BIG.

This is distinct from the total ARG_MAX limit — even if total argv is well under 2 MB, a single argument over ~128-200 KB (depending on page size) is rejected by the kernel. Reducing other args or trimming total payload size does not help. This is a hard blocker for running multi-agent workflows on Linux today. See:

• iloom-ai/iloom-cli#797 — il spin fails with E2BIG on Linux
• #21423 — the SDK's @filepath fallback for --agents doesn't work on Windows either

The --system-prompt flag already has a file-based counterpart (--system-prompt-file). The --agents flag should follow the same pattern.

Proposed solution

Add --agents-file <path> that:

1. Reads the file at <path>
2. Parses it as JSON
3. Uses the result identically to --agents <json>

This keeps the agents payload out of argv entirely, avoiding per-argument kernel limits on all platforms.

Workarounds considered

| Approach | Why it doesn't work |
|----------|-------------------|
| --agents "$(cat file.json)" | Shell expands into argv — same per-arg limit applies |
| @filepath syntax (SDK) | Buggy on Windows (#21423); SDK only triggers at 100K chars on Linux, and the CLI may not parse it correctly |
| Reduce payload size | The per-arg limit is the constraint, not total size — a 215 KB agent definition simply cannot be passed as a single CLI argument |
| Pipe via stdin | --agents doesn't read from stdin |

Environment

• Platform: Linux 6.8.0-90-generic (Ubuntu)
• Claude Code invoked via iloom-cli (il spin)
• --agents payload: ~215 KB (exceeds MAX_ARG_STRLEN)
• exec fails with spawn E2BIG

Related issues

• #21423 — @filepath syntax for --agents broken on Windows
• #3836 — earlier E2BIG issue (different root cause, fixed)