fix: name max_buffer_size in the buffer-overflow error message

[CryptoKylan]

When a CLI stdout message exceeds max_buffer_size, the reader raises fatally and the session ends — but the error never mentions the option that fixes it. Users reasonably conclude they have to patch the installed package (as #416 described) rather than pass one option.

Requested by @tmaxwell-anthropic on #98:

It would be nice if the error message told people they can change ClaudeAgentOptions.max_buffer_size.

#416 carried this change alongside a default increase and was withdrawn, so the uncontroversial half was never landed. This PR does not change the default.

Why this touches _errors.py

Simply appending the guidance to the guard's message does not work. CLIJSONDecodeError truncates its line argument to 100 characters:

super().__init__(f"Failed to decode JSON: {line[:100]}...")

That argument is meant to hold the offending JSON line; the buffer guard passes a human-readable message instead. Anything appended there is cut off mid-sentence:

Failed to decode JSON: JSON message exceeded maximum buffer size of 512 bytes. Large tool results (file reads, images, MCP ...

So hint is an optional keyword appended after the truncated line, where it always survives. It defaults to None, so every existing call site and rendered message is byte-identical — this is strictly additive.

Before / after

Before:

Failed to decode JSON: JSON message exceeded maximum buffer size of 1048576 bytes...

After:

Failed to decode JSON: JSON message exceeded maximum buffer size of 1048576 bytes... Large tool results (file reads, images, MCP responses) can exceed the default; raise it with ClaudeAgentOptions(max_buffer_size=...).

On the default

The same comment on #98 also asked:

Also, is there any reason not to set ClaudeAgentOptions.max_buffer_size to a large value? Should the default be increased?

Two reasons for caution, offered as input rather than as part of this PR:

1. The limit is the only bound on an unterminated line, so it doubles as the backstop against unbounded growth on a memory-constrained host.
2. The count is len() over a str, i.e. code points rather than bytes (max_buffer_size and import byte limits count characters instead of UTF-8 bytes #1165), so a raised limit can cost up to ~4x its nominal value for multibyte content.

Happy to follow up with a separate PR if you would like the default raised.

Testing

• python -m pytest tests/ — 1410 passed, 5 skipped
• python -m ruff check src/ tests/ scripts/ — clean
• python -m ruff format --check src/ tests/ scripts/ — clean
• python -m mypy src/ scripts/ — no issues in 31 source files

Added coverage: the hint survives line truncation, hint defaults to None, and the buffer-overflow error names max_buffer_size.