[FEATURE]: Shared precached repo/context state across subagent sessions (distinct from #6584) #51383

Feature hasn't been suggested before.

• I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

Problem Statement

Each Task/subagent invocation currently starts with a completely fresh session and no way to share a warmed-up context state with the parent or sibling subagents — even when they're actively working on the exact same repo. This is related to #6584 but distinct: #6584 asks for full conversation-history resume for a single agent across sequential calls. This issue is about a lightweight, shared base context that multiple subagents (parallel or sequential) can read from, without needing full history transfer.

Observed Impact

In a production setup running many parallel/sequential subagents against the same repository, our cache-hit-to-cache-miss ratio dropped from roughly 170:1 (single long-lived main-agent session) to roughly 1:1 once subagent-heavy workflows became the norm — even though the subagents were operating on the same codebase and largely the same static context (repo structure, conventions, key files). Each subagent effectively re-pays the full input cost for context that a sibling subagent (or the main agent) had already established moments earlier.

Use Case
A main agent spawns N subagents (parallel or sequential) to work on different parts of the same repo.
All subagents need a shared, relatively static base context: repo structure, key file summaries, conventions, relevant static config.
This base context changes slowly (only when subagents actually edit files), so it's a good candidate for reuse — but current architecture forces every subagent session to reconstruct/re-send it from scratch.
Proposed Solution

Introduce a minimal, versioned "precache state" scoped to the parent session (or project), that:

Is written once (by the main agent or the first subagent invocation) as a static, byte-stable prefix block.
Is read by all subsequent subagent invocations — parallel or sequential — instead of each one reconstructing the same context independently.
Is incrementally updated/invalidated only when the underlying state actually changes (e.g., a file edit), rather than being rebuilt per subagent call.
// Illustrative, not prescriptive
const state = await session.getPrecacheState(); // shared, versioned
const result = await invokeSubagent({
agent: "engineer",
task: "...",
precacheStateId: state.id // read-only reference, no full history
});

This is explicitly not a request for full session/history resume (see #6584) — no need to carry over a subagent's prior reasoning or tool-call history, only a shared static base.

Technical Considerations
Race conditions on parallel spawn: if multiple subagents start simultaneously, only the first should write the precache entry; others should read it once available (or fall back gracefully to an independent write).
Invalidation: needs a cheap way to detect when the shared repo/context state has actually changed (e.g., file hash / mtime) so stale precache isn't served silently.
Interaction with underlying model provider caching: as I understand it, provider-side prompt caching (e.g., Anthropic's) already matches on exact byte-identical prefixes — so part of this could potentially be solved at the OpenCode prompt-construction layer (ensuring all subagents build an identical static prefix block) without needing new session-state plumbing at all. Worth clarifying whether this is a session-architecture gap or purely a prompt-construction/plugin-layer issue.
Alternatives Considered
Manual prefix engineering — construct agent definitions so the static repo context is byte-identical across all subagent system prompts, relying on provider-side cache matching. Works today in principle, but fragile and easy to break unintentionally (e.g., differing tool sets or prompt ordering per agent).
Full session resume (#6584) — solves a related but more expensive problem; doesn't address parallel subagents that never share a lineage.
Do nothing — accept the cost overhead as the price of subagent parallelism.
Additional Context

Related: #6584 (agent-level resume). This issue is intentionally scoped smaller/cheaper: shared static context, not full history.