# Session- and auth-bound task context cache

Key and lifecycle in-process task-context caches by session id and live auth generation so shared-process sessions and mid-session auth replace cannot leak or reuse stale context.

Exact reference: {"kind":"skill_version","skill_id":"skl_wCKU3ytdp9mfmqZocBWzrA","version_id":"skv_YB8_SAYnBhcISn-q6NdzBA"}

Applicability: []

# 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 sessionId plus authGeneration. If a process-wide epoch or auth-lineage identity is used to survive counter restart, fold that epoch or lineage id into the same composite key. 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. If ALS may be lost after await or across worker boundaries, fail closed to empty or default rather than guessing sessionId.
2. Look up by the full composite key. Do not select by sessionId alone. After any await on a read or inject path, re-resolve live generation immediately before the composite lookup. 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, pin or hold the revoke critical section through prompt mutation so re-validation that entry.authGeneration equals live.authGeneration and mutation are indivisible with respect to bump and credential publish. A bare check-then-inject without that indivisibility is not equivalent. On mismatch, abort to empty or default.
4. Default-isolate child sessions. If inheritance is required, copy-on-create a snapshot into the child key and store parentLineageGeneration (or equivalent lineage epoch) on the entry—not only the child live authGeneration when the child handle uses an independent counter. Children must read the live parent auth handle for lineage checks. Maintain a parent-to-child or auth-lineage index so revoke sweeps every tied key by lineage invalidation, not numeric comparison across independent child counters.
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. For concurrent writers at the same generation, use per-key versioning or last-writer conflict detection so inject cannot silently pick arbitrary divergent payloads.
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 entries whose parentLineageGeneration is less than the new parent generation, and credential publish). On CAS failure, retry or abort without publishing.
8. Treat injected context as prompt data only—never as a network credential. Every outbound network or tool call must mint or present a capability from a single atomic snapshot read of the live handle so credentials and generation cannot tear across a concurrent replace; 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. When generation counters can restart across reload, processEpoch is mandatory in the composite key, not optional.

## 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.
- Model may plan from semantically stale prompt while network gate uses fresh credentials.
- 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, cross-generation prompt and credential mix from non-indivisible inject, stale-generation miss after await, torn outbound capability minting across auth replace, 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, child inherited entries surviving parent revoke due to independent counter domains, ALS propagation loss causing wrong-session lookup, and same-session auth-rotate paths where stale cache entries authorize network activity or reappear under a recycled session identity or restarted generation counter.

## Supporting basis and limitations

Deductive review of the corrected design by an independent native subagent in the same conversation thread. No repository inspection and no executed tests. Findings align with known concurrency and multi-counter invalidation pitfalls.

## Change and rationale

Close seven gaps from independent subagent review: child lineage generation for inherited snapshots, inject generation pin, atomic child index registration, atomic handle snapshot definition, same-generation write conflict rule, mandatory processEpoch when counters can restart, and ALS propagation failure handling.

Independent review found parent revoke can miss child entries when child authGeneration is an independent counter domain; inject TOCTOU and index races remain unless explicitly specified; network gate needs defined atomic snapshot semantics.