Session- and auth-bound task context cache

Key in-process task-context caches by session, live auth generation, and content revision; isolate shared-process sessions, survive mid-session auth replace, and keep prompt data separate from network authority.

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.

Practical steps

1. Composite key. Key every immutable entry by authLineageId, sessionId, authGeneration, contentRevision, processEpoch when generation counters can restart, and childBindingId for forked child sessions. Resolve authGeneration from the live authorization handle at every write, read, and inject—never from a module-level pointer or request-scope cache alone. Carry only sessionId in request scope such as AsyncLocalStorage; if scope is lost after await or across worker boundaries, fail closed to empty or default.

1. Separate content revision from auth generation. Bump contentRevision for content-only updates under stable auth; bump authGeneration only on revoke or replace. Bind each model turn to an explicit contentRevision in a turn lease—never inject implicit latest. Concurrent writers at the same generation use compare-and-set on contentRevision or explicit conflict detection.

1. Exact lookup, fail closed. After any await on read or inject, re-resolve the full composite key from live handles immediately before lookup. Missing key, generation mismatch, or stale parentLineageGeneration on inherited child entries yields empty or default inject. Never fall back to parent, sibling, latest, or prior generation.

1. Auth replace as atomic handle fan-out. Under one revoke critical section: tombstone all entries matching exact predicate (authLineageId, authGeneration) including child lineage entries; cancel queued work tagged with old generation; bump every bound authorization handle—root, child, and in-flight continuations—so new credentials and new authGeneration become observable together; signal in-flight workers to abort or re-check at commit. Do not publish a bumped generation while credentials remain stale or absent. On swap failure after tombstone, fail closed on network and inject.

1. Scoped tombstone predicate. Tombstone only entries whose authLineageId and authGeneration match the revoked generation. Never tombstone by generation value alone across lineages or sessions.

1. Child fork with writer isolation. Copy-on-create a sanitized snapshot with childBindingId and parentLineageGeneration stamped at fork time. Install snapshot and register lineage index in the same critical section that blocks parent writers, producing a true point-in-time slice. At every child inject and read, re-validate live parent lineage generation; parent replace invalidates inherited entries when parent generation exceeds stamped fork generation.

1. Inject as generation-validated lease with pinning. Minimum synchronous unit: read live generation and turn-bound contentRevision, select entry under full composite key, verify generation and parent-generation match, increment pin refcount, copy pinned bytes into the message buffer, release pin. After any await, repeat the entire unit—never reuse a pre-await pin or entry reference. Tombstone rejects new pins; LRU eviction cannot drop pinned bytes.

1. Prompt data versus network authority. Cached context is prompt data only—never embed credentials or pre-approved scopes. Every outbound call mints a short-lived capability from one atomic live-handle snapshot at redemption time. Tag queued dispatches with authLineageId and authGeneration; reject mismatch at the gate before spawning workers or opening sockets. Re-check live generation before applying any async side effect—cache writes, tool registry, filesystem view, feature flags—not cache alone.

1. In-flight worker write commit. Workers that passed an earlier gate must re-check live generation at write commit. Tombstone or generation mismatch aborts the write; never revive stale-generation entries after cancel.

1. Memory bounds. Cap bytes per entry, per session, and process-wide. Delete-on-bump as primary eviction; LRU plus TTL for orphans. Account pinned snapshots, pin refcounts, and queued work in budgets.

Limits

• Does not scrub prompt text already injected into an in-flight model turn before auth replace.
• Cannot recall bytes already on the wire under a prior generation.
• Model may plan from semantically stale prompt while network gate uses fresh credentials.
• Does not define distributed revocation protocol, capability format, or crash-recovery store.
• Support is reasoned analysis and independent adversarial design review in the source conversation, not executed tests.

Failure prevented

Prevents cross-session context injection; stale context surviving auth replace; child handles diverging from parent swap; implicit latest revision skew; cross-lineage tombstone collateral; inject TOCTOU across await or concurrent replace; stale inherited child prompt after parent revoke; pin eviction use-after-free; stale cache or prompt data authorizing network activity; generation-gated cache but ungated session side effects; partial fork snapshots under concurrent parent writers; and unbounded memory from orphaned generations or idle sessions.