[Bug] --agents accepts invalid JSON with exit 0 and no warning, while --settings/--mcp-config reject it

The inconsistency here is a real operational hazard, especially in CI. The --settings and --mcp-config flags error on malformed JSON because those are load-bearing configs where the tool cannot proceed safely without them. --agents should follow the same convention.

The silent-success behavior means anyone generating the --agents value programmatically (templating agent definitions from a deploy script, JSON-encoding in bash with variable substitution, etc.) will get a phantom success on broken configs. Your session runs fine, your agents never existed, you find out 20 minutes later when the expected behavior never happens.

Two things that would fix this:

1. Parse and validate --agents JSON before the session starts, exit 1 on malformed input (same as --settings).
2. On startup, print the resolved agent list so there is a visible audit trail: "Loaded 3 agent definitions: architect, reviewer, implementer." A single INFO line catches the "agents silently not loaded" case even if validation somehow passes.

The second point is useful even when JSON is valid -- it closes the "did my agent definition actually load" guesswork that is common when debugging agent behavior.

Reproduced on v2.1.233 (macOS).

Steps:

1. claude -p 'say ok' --agents '{bad json'; echo $?
2. claude -p 'say ok' --settings '{bad json'; echo $?
3. claude -p 'say ok' --mcp-config '{bad json'; echo $?

Observed:

$ claude -p 'say ok' --agents '{bad json'; echo $?
OK
0
$ claude -p 'say ok' --settings '{bad json'; echo $?
Error: Settings file not found: {bad json
1
$ claude -p 'say ok' --mcp-config '{bad json'; echo $?
Error: Invalid MCP configuration:
MCP config file not found: .../{bad json
1

--agents also silently accepts wrong-shaped but valid JSON (for example --agents '{"reviewer": "not an object"}' or an agent object missing prompt) with exit 0 and no output.

Expected: --agents should fail (or at least warn) on malformed or wrong-shaped JSON, matching --settings and --mcp-config, so scripts do not silently run without the agents they asked for.

Assessment: This is intended today rather than a regression — --agents deliberately fails soft: bad JSON or a definition that doesn't match the schema is dropped and only recorded in the debug log (visible with --debug), and this has been the behavior since the flag was added. The docs (https://code.claude.com/docs/en/cli-reference, https://code.claude.com/docs/en/sub-agents) don't say what happens on invalid input. But the expectation is reasonable: the sibling flags validate up front and exit non-zero, and silently running without the requested agents is exactly what automation can't detect. We should make this clearer by validating --agents at startup the same way --settings and --mcp-config are validated, printing the parse/schema error to stderr and exiting non-zero (or at minimum emitting a visible warning).

🤖 Generated with Claude Code

Confirmed — reproduced on 2.1.233 on Linux.

What I ran:

• claude -p "hi" --agents '{invalid json' → no error, no warning; the session runs exactly as if the flag hadn't been passed (exit 0 with working auth). The invalid value is silently discarded, and the same happens for structurally wrong JSON.
• claude -p "hi" --settings '{invalid json' → immediate error, exit 1.
• claude -p "hi" --mcp-config '{invalid json' → immediate error, exit 1.

So --agents really is inconsistent with the other two config flags, and a shell-quoting mistake in CI means your agents silently don't exist. We agree it should fail fast (or at minimum warn) like --settings does — thanks for the clear report.

🤖 Generated with Claude Code