fix(bridge): pass explicit max_buffer_size to the Claude SDK

[jinon86]

Problem

The bridge lost a whole turn on 2026-08-03 18:19:14 KST:

claude_agent_sdk._internal.query - ERROR - Fatal error in message reader:
Failed to decode JSON: JSON message exceeded maximum buffer size of 1048576 bytes

Cause chain (all verified against the installed SDK, claude-agent-sdk 0.2.128):

• claude_agent_sdk/_internal/transport/subprocess_cli.py:30 — _DEFAULT_MAX_BUFFER_SIZE = 1024 * 1024 (1 MiB)
• same file, 143-146 — when options.max_buffer_size is None, that 1 MiB default is used
• same file, 972-976 — a single NDJSON line over the limit raises SDKJSONDecodeError, killing the message reader task. There is no recovery path, so the whole turn fails.
• the bridge never set max_buffer_size anywhere, so it always ran on the 1 MiB default.

The line that actually killed the reader was 1,056,854 bytes — only 8,278 bytes over the limit. A 510 KB PNG screenshot went through the Read tool; Claude Code resized and re-encoded it to 682x2000 (528,000 base64 chars) and then shipped that same base64 twice in one message: once as message.content[0].content[0].source.data and again as toolUseResult.file.base64. That duplication doubles the payload, so the effective failure threshold is only ~524 KB of base64 for a single image — reached routinely by ordinary screenshot/image work.

Change

ClaudeRuntime._build_options now always passes an explicit max_buffer_size. The value is resolved once in __init__, deliberately outside the settings-bound branch, so the bare settings-free construction path (unit tests, the conformance harness, any future caller that forgets to bind settings) cannot fall back to 1 MiB either.

New setting, following the existing alias= convention in bridge/utils/config.py:

Variable	Default	Range
CCC_CLAUDE_MAX_BUFFER_SIZE	16777216 (16 MiB)	1 MiB – 256 MiB

• 16 MiB leaves ~16x headroom over the measured fatal line (about 8 images' worth of the duplicated encoding). It bounds a buffer; it does not preallocate memory.
• The floor is the SDK's own 1 MiB: configuring anything lower is strictly worse than the bug this replaces, so Config rejects it.
• Malformed / out-of-range values reaching the adapter degrade to the default rather than failing session start — a mistyped buffer bound must not take the bridge down.
• The default is single-sourced in runtime_config_check.py (stdlib-only, already the home of DEFAULT_PROCESS_TIMEOUT_SECONDS) so config.py and claude_runtime.py cannot drift.

Per repo convention the measured numbers are recorded in the code comments, not just here.

Files

• bridge/runtime_config_check.py — DEFAULT_CLAUDE_MAX_BUFFER_SIZE / MIN_ / MAX_ + incident rationale
• bridge/utils/config.py — claude_max_buffer_size field, alias CCC_CLAUDE_MAX_BUFFER_SIZE
• bridge/core/claude_runtime.py — _resolve_max_buffer_size(); explicit max_buffer_size= on ClaudeAgentOptions
• bridge/tests/test_claude_max_buffer_size.py — new, 19 tests
• bridge/.env.example, bridge/README.md, bridge/CLAUDE.md — operator discoverability
• CHANGELOG.md, bridge/CHANGELOG.md

Tests

New suite covers (a) the default, (b) env override + out-of-range rejection, (c) the value actually reaching ClaudeAgentOptions on both the settings-bound and bare paths, plus a guard pinning the SDK's own 1 MiB constant so the rationale cannot go stale silently.

tests/test_claude_max_buffer_size.py .......  19 passed

full bridge suite (CI command, python 3.12):
python -m pytest -q --cov=telegram_bot --cov-report=term
2169 passed, 1 skipped, 3 warnings, 271 subtests passed in 258.35s
Required test coverage of 80.0% reached. Total coverage: 81.93%

umask-0002 variant: 37 passed
CI hardening regressions:  35 passed
ruff check .   All checks passed!
mypy           Success: no issues found in 81 source files

Source-only change. No live tree, service, or deployment was touched.

🤖 Generated with Claude Code

[seoseo-ai]

Approved after explicit operator authorization using the local seoseo-ai credential.