[FEATURE] Large Tool Result Externalization via AfterToolCallEvent Hook

[westonbrown]

Problem Statement

When tool outputs exceed the model's context capacity, the SDK's current handling in SlidingWindowConversationManager replaces the entire result with a generic message:

tool_result_too_large_message = "The tool result was too large!"

This approach has two problems:

1. Data loss - Full output is discarded permanently
2. Reactive timing - Only triggers after context overflow, wasting a failed API call

For tools that return large outputs (file readers, API responses, database queries, log analyzers), the agent loses the ability to reference or reason about the content.

Proposed Solution

Add a hook-based mechanism to intercept large tool results via AfterToolCallEvent before they enter the conversation:

1. Detect outputs exceeding a configurable threshold (e.g., 10KB)
2. Persist full output to an artifact file on disk
3. Replace the conversation content with a truncated preview plus artifact reference

Example output injected into conversation:

[Output: 125,432 chars | Full: artifacts/shell_20241124_143022.log]

<first 4,000 characters as preview>

[Complete output saved to: artifacts/shell_20241124_143022.log]

Context window benefits:

• 125KB output reduced to ~5KB in conversation (preview + reference)
• Proactive reduction at tool execution time, not after overflow
• Prevents large outputs from ever consuming context space

Use Case

1. Context efficiency - Large outputs handled proactively, keeping context window clean for reasoning
2. Long-running agents - Process large datasets, logs, or API responses without context pressure
3. Debugging and auditing - Full outputs preserved on disk for review
4. Multi-step workflows - Intermediate results retrievable via artifact path if needed later

agent = Agent(
    hooks=[LargeResultExternalizerHook(
        threshold=10000,      # Externalize outputs > 10KB
        artifact_dir="./artifacts",
        preview_size=4000     # Keep 4KB preview in context
    )]
)

Alternative Solutions

• Aggressive truncation (current approach) - loses data permanently, reactive only
• In-memory compression ([FEATURE] PruningConversationManager for Selective Message Compression #556) - reduces size but still consumes context
• Manual tool wrappers - requires per-tool implementation

Artifact externalization complements #555 (proactive compression) and #556 (pruning) by reducing context consumption at the source while preserving full data.

Additional Context

This operates at a different layer than conversation management:

• Triggers on AfterToolCallEvent (before conversation manager sees it)
• Proactively reduces context consumption at tool execution time
• Preserves full output to disk for retrieval
• Provides immediate preview for LLM reasoning

Related: #555 (proactive compression), #556 (pruning), #1294 (token estimation), #1295 (context limit)