Session- and auth-bound task context cache

When to use

Use when an agent plugin caches task context before a system-message transform, multiple root or child sessions share one process, and authorization may be revoked or replaced while that process and root session stay alive.

Steps

1. Key every entry as the pair sessionId plus authGeneration. Carry only sessionId in request scope such as AsyncLocalStorage. Resolve authGeneration from the live authorization handle for that auth lineage at write, read, and inject time—never from a module-level current pointer and never from an ALS-cached generation alone.
2. Look up by the full composite key. Do not select by sessionId alone. Missing or generation mismatch injects empty or default. Never fall back to parent, sibling, last-writer, or a prior generation.
3. After a successful fetch and immediately before mutating prompt state, re-validate that entry.authGeneration equals live.authGeneration inside the revoke critical section or an equivalent load-check-inject sequence. On mismatch, abort to empty or default. Do not treat a loaded payload as safe to inject across a concurrent bump.
4. Default-isolate child sessions. If inheritance is required, copy-on-create a snapshot into the child key; never share a mutable object with the parent. Children must read the live parent auth handle for generation checks. Maintain a parent-to-child or auth-lineage index so revoke sweeps every tied key.
5. Sample generation once at the start of a write. Key and tag the entry only with that sampled generation. On commit, inside the same critical section used for revoke or an equivalent compare-and-set, require sampled equals live; only then insert or replace. On mismatch, abort and delete any provisional entry under the sampled key. Never re-resolve live into the composite key after a bump.
6. Serialize child snapshot creation and lineage-index registration with that same critical section. Treat entry install and lineage registration as one atomic unit. If using post-insert re-validation instead, on mismatch delete the child entry and remove the index edge so revoke cannot mis-sweep or skip.
7. On revoke or replace: compare-and-set live.authGeneration from expected to expected plus one (or hold one critical section for the whole bump, lineage delete or tombstone including indexed children, and credential publish). On CAS failure, retry or abort without publishing. Do not rely on a post-bump check that live still equals the bumped value alone when bump, delete, and publish may be only partially serialized.
8. Treat injected context as prompt data only—never as a network credential. Every outbound network or tool call must present a capability bound to the current generation; mismatch fails closed. Cancel work that will take another hop; do not assume already-gated single-shot I/O is recalled. Re-check live generation before applying response side effects.
9. Bound memory: cap entry count, bytes per entry, and total bytes; prefer delete-on-bump and session dispose; use LRU plus TTL for orphans; store slim summaries. Do not recycle a sessionId while an orphaned composite entry for that id may remain, or else use a process-wide epoch or otherwise unique generation space so restarted counters cannot collide.

Limits

• Does not scrub prompt text already injected into an in-flight model turn before a bump.
• Cannot recall bytes already on the wire; re-check live generation before applying response side effects.
• Completed single-shot I/O under an old generation is not undone.
• Support for this guidance is reasoned analysis and independent design review, not executed tests.

Failure prevented

Prevents cross-session context injection, inject of a payload loaded before a concurrent revoke, late-writer orphan or reinstall of a revoked generation, write-key poison onto a post-bump generation, child snapshot and lineage-index races across parent auth replace, and same-session auth-rotate paths where stale cache entries authorize network activity or reappear under a recycled session identity.