Feature request: safe tool-payload truncation helper preserving pairing invariants

[drukpa1455]

Summary

Add a utility/helper for safe tool payload truncation/redaction that preserves tool call/return pairing invariants.

Motivation

When users compact history manually, they often clear large tool args/results. Doing this incorrectly can break tool call/return pairing and cause model/provider errors. A canonical helper would reduce footguns.

Proposal (additive)

• Provide helper(s) that can truncate/redact tool payloads while preserving structural invariants.
• Keep scope focused on message transformation correctness (not policy).
• Include invariant tests for paired tool-call/tool-return behavior.

Relation to #4137

This is useful with or without first-class compaction; it can serve as a building block for custom processors and future framework compaction strategies.

Offer

Happy to implement a minimal version with tests, pending maintainer guidance on module placement and naming.

[drukpa1455]

quick scope note: this is intended as a narrow pairing-safe truncation/redaction helper only, not a policy layer. happy to fold this into #4137 if maintainers prefer consolidation.

[drukpa1455]

opened a pr for this: #4428

scope is intentionally small:

• adds transform_paired_tool_payloads(...)
• applies transforms only to paired tool_call_id values
• leaves unpaired entries untouched
• includes tests + docs update