atomic-post-await-state-commit

SKILL: Atomic Post-Await State Commit

Domain: tool-orchestration
Trigger: Use this pattern when concurrently persisting large tool results and mutating ContentReplacementState once the awaited work completes, such as the freshReplacements loop inside enforceToolResultBudget. Source Pattern: Distilled from reviewed tool-loop and result-shaping patterns.

Core Method

Await all selected persistence jobs, then in the same synchronous loop mark each tool_use_id as seen and, if persistence succeeded, place the preview string into both the local replacement map and the shared ContentReplacementState.replacements. The state mutation happens after the await so other threads or resumed contexts never observe the ID as seen without its replacement (or vice versa), keeping the decision atomic.

Key Rules

• Never add a tool_use_id to seenIds before the persist promise resolves; doing so risks another thread classifying the ID as frozen while the replacement string has yet to materialize.
• Mark the ID as seen even when persistence fails so the failure case still freezes the original content and prevents reprocessing the same bytes later.
• When persistence succeeds, update state.replacements and replacementMap together so immediate replays see the cached preview string with the same bytes that triggered the log/event.
• Keep the loop synchronous after the await; avoid spreading the state updates across callbacks or other async code paths that might observe partial state.

Example Application

Inside enforceToolResultBudget, freshReplacements combines each candidate with the result of buildReplacement. The for-loop that follows immediately adds every candidate to state.seenIds, then conditionally sets state.replacements if a preview exists. That ensures when the same tool_use_id reappears (for example during a resume or in a forked agent) the code re-applies the cached preview without re-persisting the file.

Anti-Patterns (What NOT to do)

• Do not call state.seenIds.add before awaiting persistence; the race can produce mustReapply entries without a matching cached preview.
• Do not leave the replacements map empty after a successful persist; otherwise applyToolResultBudget will treat the ID as seen-but-unreplaced and may persist it again later.
• Do not split the success and failure branches across multiple awaits or microtasks; the observer must never see a seen entry without the corresponding replacement when one exists.