fix: bound oversized tool-result text at ingress

[Brian Krabach (bkrabach)]

Summary

A single oversized tool result could remain protected through every compaction level and reach the provider unchanged (the 3.16 MB reproduction). This adds a default-on ingress guard that bounds direct tool-result text before it enters canonical context or resume state.

• Default max_tool_result_bytes = 131072 UTF-8 bytes; one explicit constructor/config setting supports legitimate larger text.
• Clips a UTF-8-safe prefix and emits one visible retrieval marker plus numeric, non-payload telemetry.
• Preserves tool call IDs, status/metadata, pair integrity, and typed image/audio/unknown blocks.
• Does not retain the clipped original; guidance recommends narrower reads/queries and forbids repeating state-changing actions merely to recover output.
• Intentionally does not change general conversation limits, native compaction, estimators, rolling budgets, spill, per-tool rules, or add an off switch.
• Documents the finite operational baseline: 509 outputs from 16 stock-main S1 captures, p99 40,139 bytes, maximum 87,301 bytes, none above 128 KiB.

Verification

Local commands and results:

• uv run pytest -q tests/test_tool_result_ingress.py — 19 passed
• uv run pytest -q — 124 passed, 1 xfailed
• uv run ruff check . — clean
• uv run python -m compileall -q amplifier_module_context_simple tests — pass
• README first TOML fence parsed with tomllib; max_tool_result_bytes == 131072

The focused regression test_default_caps_the_real_oversized_protected_tool_result_before_compaction reproduces the prior failure condition and verifies the result is bounded before compaction. The pre-fix local receipt recorded the 3,163,313-byte result remaining unchanged at compaction level 8; the implementation now bounds it at ingress.

Prepared real-provider validation covered four flows across Anthropic and OpenAI: normal 77,129-byte results were unchanged with zero ingress events; oversized serialized 3,163,313-byte results became 131,072 bytes in context and the next provider request with one event; nonce-only tail retrieval passed; no provider errors, 400s, fallback, or level-8 compaction occurred. This was a prepared streaming-orchestrator/provider harness, not a full Click CLI run.

Breaking changes

Oversized direct tool-result text is now irreversibly clipped by default before admission. Callers that legitimately need larger text must explicitly raise max_tool_result_bytes.