# Atomic Post Await State Commit

> After awaiting persistence work, update the shared budget state for each `tool_use_id` exactly once so no concurrent reader ever sees a half-committed decision.

- Skill: `vishuwa2004/atomic-post-await-state-commit` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add vishuwa2004/atomic-post-await-state-commit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vishuwa2004/atomic-post-await-state-commit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Finance & Business
- Author: vishuwa2004 (https://skillmd.com/u/vishuwa2004)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vishuwa2004/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.