# 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.

Exact reference: {"kind":"skill_version","skill_id":"skl_wCKU3ytdp9mfmqZocBWzrA","version_id":"skv_dC2cuXE3H_fqcK2E66xCsQ"}

Applicability: [{"constraint":"Shared process with root and child sessions caching task context before system-message transform","technology":"Agent plugin architecture","version_scheme":"unknown"},{"constraint":"Authorization may be revoked or replaced while process and root session stay alive","technology":"Authorization systems","version_scheme":"unknown"}]

# 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.

## Practical steps

1. **Composite key.** Key every immutable entry by authLineageId, sessionId, authGeneration, contentRevision, and when generation counters can restart, processEpoch. Also use 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.

2. **Separate content revision from auth generation.** Task context can change without auth rotation. Bump contentRevision for content-only updates under stable auth; bump authGeneration only on revoke or replace. Exact lookup requires full key match including contentRevision. Concurrent writers at the same generation use compare-and-set on contentRevision or explicit conflict detection—never silent last-writer ambiguity.

3. **Exact lookup, fail closed.** After any await on read or inject, re-resolve live authGeneration 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.

4. **Auth replace as atomic handle swap.** Under one revoke critical section: tombstone or delete all entries for the old generation including lineage-indexed children; cancel queued work tagged with old generation; perform atomic swap so new authGeneration and new credentials become observable together. Do not publish a bumped generation while credentials remain stale or absent. On swap or publish failure after tombstone, fail closed on network and inject; do not resurrect old entries without an explicit recovery protocol.

5. **Child fork linearization.** Copy-on-create a sanitized snapshot with childBindingId and parentLineageGeneration stamped at fork time. Serialize snapshot install and lineage-index registration in the same critical section as parent generation checks. At inject, re-validate live parent lineage generation; parent replace invalidates inherited entries when parent generation exceeds stamped fork generation.

6. **Inject as generation-validated lease.** Minimum atomic unit: read live generation, select entry under full composite key, verify generation match, copy pinned bytes into the message buffer. Do not hold revoke locks through full prompt assembly or subresource awaits. A bare check-then-inject outside this unit is insufficient.

7. **Prompt data versus network authority.** Injected 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; redemption must be indivisible with revocation at one authority boundary or validated remotely. Tag queued dispatches with authLineageId and authGeneration; reject mismatch. Re-check live generation before applying response side effects to cache.

8. **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 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 design review in the source conversation, not executed tests.

## Failure prevented
Prevents cross-session context injection; stale context surviving auth replace; generation observable before credentials are consistent; content updates under stable auth breaking immutability or exact lookup; child inherited entries surviving parent revoke due to fork or index races; inject TOCTOU across concurrent replace; stale cache or prompt data being mistaken for network authority; and unbounded memory growth from orphaned generations or idle sessions.

## Supporting basis and limitations

Reasoned analysis across this conversation thread: baseline session isolation design, auth-generation extension, and independent native subagent review (PASS WITH GAPS, four concrete errors identified and addressed). No repository inspection and no executed tests.

## Change and rationale

Correct auth-replace ordering to atomic handle swap; add contentRevision separate from authGeneration; define inject as generation-validated lease with minimal atomic copy unit; tighten child-fork linearization and replace-failure fail-closed behavior per independent design review in source conversation.

Prior version allowed generation to become observable before credentials were consistent, conflated auth rotation with content updates, and left inject-pin semantics ambiguous. This update closes those specification gaps while preserving the existing session-isolation and network-gate model.