fix(#842): total SessionStart byte budget, handoff redelivery cap, and a config-aware oversize notice - #845

SessionStart had no limit on its total output. Claude Code saves any hook output over roughly 10,000 characters to a file and shows the model only a short preview. On ordinary stores (11–14.7KB, measured by the reporter), that preview ends inside the handoff, so the whole MEMORY section (now, recent, today, archive) never reaches the model.

This covers requests 1, 3 and 4 from #842. Request 2 (session_start.inject_files) is deferred. The config-cache bug from the same report is #843 / #844.

• Total budget (request 1): new thresholds.session_start_max_bytes, default 9000; 0 turns it off.
  • The handoff and memory output is collected into one variable before printing, so the budget can see the whole total.
  • If the total is over budget, whole sections are dropped, lowest priority first: archive, then today, recent, now. Each dropped file is listed by path and size, the way source=compact already lists files. Nothing is truncated partway through a file.
  • source=compact is unaffected.
  • The budget counts bytes, not characters. A byte count is never smaller than the character count, so this is the stricter of the two.
• Handoff repeats (request 3): new thresholds.handoff_max_redeliveries, default 3. Once the same handoff has been shown in full N times, later starts list it by path and size instead of re-injecting it. The delivery count still goes up, and /remember still replaces the handoff as before.
• Over-cap notice (request 4): when memory_inject_max_bytes is set below the bundled default, the notice says "capped by config" and no longer points to /remember:doctor.
• Bad values: a malformed value in either new key is logged as a WARNING and falls back to the default.
• Docs: docs/configuration.md and config.example.json. tests/test_config_contract.py passes.

Closes #842

Measured

On a test store sized like the one in the report:

• Before: 12,890 bytes of SessionStart output, over the cap.
• After: 6,740 bytes. Archive and today are listed by path and size instead of injected.

Testing

23 new tests, each written first and watched fail before the change: 11 of 23 failed then, and all 23 pass now.

• tests/test_session_start_total_budget_842.py (11). Covers: under budget (control), drop order, dropped files listed with their size, total stays under the budget, every file just under its per-file cap, a store with lots of multi-byte text, 0 turning the budget off, a malformed value, and compact unchanged (control).
• tests/test_handoff_max_redeliveries_842.py (8). Covers: below the threshold (control), listed instead of injected on the 4th delivery, the count still going up, a new handoff resetting the count (control), 0 turning the cap off, a lower configured threshold, and a malformed value.
• tests/test_memory_inject_capped_notice_842.py (4). Covers: a lowered cap gets the new wording; at or above the default keeps the original wording (controls).
• Full pytest: 2820 passed, 59 skipped, 0 failed.
• Bash 3.2: wrapping the block in $( { … } ) broke two existing case blocks under the stock bash 3.2.57, a parse error caught while developing this. They now use the leading ( pattern form this file already uses elsewhere for the same reason.

Review notes

• The captured block: about 360 lines of session-start-hook.sh now run inside $( … ). I followed the 38 functions called from it. No variable set inside is read after it, no background job starts inside it, and nothing inside writes to the real terminal output directly or calls exec or exit.
• Not in the budget: output printed after the captured block. That includes the consolidation notice, the slow-start notice, and after_session_start plugin output. The default of 9000 leaves about 1000 bytes of room under the 10K cap for these.
• Promo path: when a promo is showing, the output is wrapped in JSON, and escaping makes it larger. It's unknown whether Claude Code's cap counts the raw output or the additionalContext text.

Cross-platform claims

• Observed on macOS with bash 5.3 and stock /bin/bash 3.2.57.
• Reasoned, not observed, on Linux and Windows Git Bash. The three new test files are skipped on Windows (they need a bash hook subprocess), and are listed in docs/windows-skip-triage.md. CI covers the matrix.

🤖 Generated with Claude Code

[AI-generated]