Feature Request: Configurable Tool Output Limits for Token Optimization

Feature Request: Configurable Tool Output Limits for Token Optimization

Summary

Add opt-in, configurable tool output truncation at the CLI level to prevent excessive token consumption from verbose tool outputs in conversation history.

Problem Statement

In multi-agent and automation-heavy Claude Code workflows, tool outputs (Bash, Read, Grep, Glob) contribute 20-30% of token overhead. Large tool outputs are stored in full in conversation session files (.jsonl) and loaded on every session continuation, causing significant token waste.

Real-World Example

# Agent runs
journalctl -u redis-server

# Returns 50,000 lines (2MB of logs)
# This 2MB is stored in session.jsonl
# Session gets continued 10 times
# That 2MB gets loaded 10 times = 20MB of redundant data transfer
# Cost: ~5M tokens wasted

Impact

• Our multi-agent system analysis shows 20-30% token overhead from tool outputs
• With 206 agent spawns/day, this translates to $50-100/day in excess costs
• Problem compounds in long-running sessions with multiple tool invocations
• Especially severe for multi-agent systems where sessions are frequently continued

Relationship to Existing Issues

This is different from #12728 (MCP Output Verbosity Control):

• #12728: Controls what user sees in terminal (display)
• This request: Controls what gets stored in conversation history (storage)
• Complementary: Both address verbosity but at different layers

Also related to #15526 (Task Output excessive context) but this provides a general solution for all tools, not just Task Output.

Proposed Solution

1. Configuration Schema (settings.json)

{
  "toolOutputLimits": {
    "bash": {
      "maxBytes": 10240,
      "truncationMessage": "... (output truncated, {bytes} total bytes, {lines} total lines)"
    },
    "read": {
      "maxBytes": 51200,
      "preserveStart": true,
      "preserveEnd": true,
      "contextLines": 10,
      "truncationMessage": "... (file continues, {lines} more lines, {bytes} more bytes)"
    },
    "grep": {
      "maxResults": 100,
      "truncationMessage": "... ({total} total matches, showing first {shown})"
    },
    "glob": {
      "maxResults": 200,
      "truncationMessage": "... ({total} total files, showing first {shown})"
    }
  }
}

2. Truncation Behavior

Bash (byte-based truncation):

[First 10KB of output]
... (output truncated, 50,240 total bytes, 1,000 total lines)

Read (intelligent start+end preservation):

[First 25KB of file]
... (file continues, 4,500 more lines, 175KB more bytes)
Use Read with offset/limit parameters to access full content.
[Last 25KB of file]

Grep/Glob (result count limiting):

[First 100 matches]
... (1,000 total matches, showing first 100)
Use head_limit parameter to cap results.

3. Key Design Principles

Opt-in, not breaking:

• Default: No limits (backward compatible)
• Users must explicitly configure limits in settings.json
• No existing workflows broken

Preserves functionality:

• Truncation messages clearly indicate what happened
• Show totals so agent knows scale of data
• Agent can still access full content via:
• Re-running command with smaller scope
• Using offset/limit parameters for Read
• Reading/processing in chunks

Configurable per-tool:

• Different tools have different needs
• Bash might need 10KB, Read might allow 50KB
• Each tool gets appropriate threshold

Implementation Notes

Where to Truncate

Tool executes → Output generated → [TRUNCATION LAYER] → Conversation history storage

Truncation should happen:

• After tool execution completes
• Before writing to session .jsonl file
• Still show full output in terminal (or respect #12728 if implemented)

Truncation Strategies

For byte-based limits:

if (output.length > maxBytes) {
  const truncated = output.substring(0, maxBytes);
  const message = formatTruncationMessage(output.length, maxBytes);
  return truncated + message;
}

For result-based limits (Grep/Glob):

if (results.length > maxResults) {
  const truncated = results.slice(0, maxResults);
  const message = `... (${results.length} total, showing first ${maxResults})`;
  return truncated + message;
}

For intelligent start+end (Read):

if (content.length > maxBytes) {
  const keep = maxBytes / 2;
  return content.substring(0, keep) +
         formatMiddleMessage(hiddenLines, hiddenBytes) +
         content.substring(content.length - keep);
}

Benefits

For Users

• Automatic protection against verbose output bloat
• Configurable thresholds per tool type
• Safety net even when agents forget to use | head or head_limit
• Transparent - clear indication when truncation occurs

For Multi-Agent Systems

• Significant cost savings (20-30% reduction in tool overhead)
• Better session management (smaller session files)
• Faster session loads (less data to parse)
• Prevents runaway costs from accidentally verbose commands

For Claude Code Ecosystem

• Benefits all users, not just our use case
• Especially valuable for automation and multi-agent workflows
• Complements existing features like context compaction
• Aligns with token optimization best practices

Alternatives Considered

1. Agent Training (Current Approach)

• ✅ Works, but requires constant vigilance
• ❌ Agents can forget to use limits
• ❌ Doesn't prevent accidents
• ❌ Requires ongoing monitoring

2. Post-processing Session Files

• ✅ Could work via external script
• ❌ Complex, fragile
• ❌ Doesn't prevent tokens from being consumed initially
• ❌ Would need to run constantly

3. CLI-level Solution (This Request)

• ✅ Automatic, always-on protection
• ✅ Opt-in, backward compatible
• ✅ Built-in, no external dependencies
• ✅ Benefits entire user base

Success Metrics

For our system:

• Expected 20-30% reduction in tool output token overhead
• $50-100/day savings
• Prevents accidental 18K-turn runaway sessions

For Claude Code:

• Provides users with cost control tools
• Reduces support burden from token cost complaints
• Aligns with best practices for efficient agent operation

Additional Context

We've built comprehensive token optimization tooling for our multi-agent system:

• Session analytics with cost tracking
• Tool output monitoring
• Best practices documentation
• Anomaly detection

This feature request represents the final piece: built-in protection at the CLI level that doesn't depend on agent behavior or external monitoring.

References

• Related Issue #12728: MCP Tool Output Verbosity Control (display layer)
• Related Issue #15526: Task Output excessive context (specific tool)
• Related Issue #16252: Token usage optimization for planning
• Our Documentation: Available at ~/claude-coordination/docs/TOOL_OUTPUT_OPTIMIZATION.md

Proposed Labels

• enhancement
• area:tools
• area:cost
• perf:memory

---

Reporter: @benfinklea
Use Case: Multi-agent Claude Code coordination system
Impact: High for automation/multi-agent workflows, Medium for general users
Priority: Medium-High