Design: Tool Result Compression for context budget optimization

[RyderFreeman4Logos]

Problem

Large tool outputs consume context budget disproportionately. When agents invoke tools that produce verbose output (e.g., large git diffs, compilation errors, search results), the raw output fills the context window, forcing premature compaction and degrading reasoning quality.

Current Mitigations

• Tail buffer: 1 MiB (collect_agent_output ring buffer)
• Spool: 32 MiB per session (spool_file in session dir)
• Event ring buffer: 10K events
• CSA:SECTION markers for structured output parsing

Constraints (must not break)

• Session replay (csa session result/logs)
• Fork-call-return (ReturnPacket protocol)
• CSA:SECTION markers parsing
• output/index.toml manifest

Proposed Direction

Add an optional summary-replacement layer after collect_agent_output():

1. When tool output exceeds a configurable threshold (e.g., 8KB), replace in-context content with a summary + file path reference
2. Write original output to {session_dir}/tool_outputs/{tool_call_id}.raw
3. Generate a compression manifest (tool_outputs/manifest.toml) for replay
4. Agent can request full output via csa session tool-output <id> if needed

Pre-requisites

• Phase C passive evaluation data (quantifies which tools produce the largest outputs and how frequently)
• Analysis of current tool output size distribution across projects

References

• HiTw93 article: context engineering and tool result management
• Cursor A/B test: 46.9% token reduction from dynamic tool discovery (analogous principle)

[RyderFreeman4Logos]

Implemented in PR #452

Tool result compression is now available as an opt-in feature.

What was implemented

1. Config: [session] tool_output_compression = true + tool_output_threshold_bytes (default 8KB)
2. Storage: Large tool outputs persisted to {session_dir}/tool_outputs/{index}.raw with TOML manifest
3. Compression logic: Runs at end of post-execution pipeline; protected markers (CSA:SECTION, ReturnPacket, final_decision:, CSA_VAR:) are never compressed
4. Retrieval: csa session tool-output <session-id> <index> for on-demand access, --list for manifest
5. Placeholder: [Tool output compressed: N bytes → csa session tool-output <id> <index>] (copy-pasteable)

Additional fixes in the same PR

• csa config get TOML parsing bug (toml 1.0 FromStr regression)
• mktd debate timeout raised to CLI minimum (1800s)
• dev2merge --force-ignore-tier-setting removed (not valid for csa plan run)
• mktd workflow STEP_N_OUTPUT variable reference alignment

Pre-requisites note

Phase C passive evaluation data was not required for the initial implementation. The 8KB default threshold is a reasonable starting point; future tuning can use actual tool output size distribution data.