docs: document package KV cache effects

packages/subagent/subagent-acp/README.md

@@ -67,12 +67,16 @@ Keyless tests drive a scripted ACP subprocess over real stdio. The with-key e2e
 
 **Token effect**: The child pays for an independent full context and its own multi-step history. These tokens never enter the parent's context.
 
+**KV Cache effect**: Independent of the parent request cache. Each ACP child can reuse only prefixes identical under its own provider, model, composition, and history; child steps otherwise grow append-only.
+
 ### Parent tool result, indirectly
 
 **What the model sees**: Through `dsh-tool-subagent`, the parent receives only the child's final streamed assistant text or that consumer's exact stop-reason error, not intermediate messages or tool traffic. A request already cancelled before publication becomes exactly `Error: subagent request was aborted before the ACP child started`; other start failures pass through as `Error: <message>`.
 
 **Token effect**: Parent input grows only by the final result or error, which is data-dependent and retained until compaction. This provider adds no parent schema itself.
 
+**KV Cache effect**: Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
 ## Known Limitations and Deferred Work
 
 - **A fresh process per run** — persistent-process pooling is a future optimization ([the seam RFC](../../../docs/rfc/implemented/feature/2026-06-21-subagent-capability-seam.md)).

packages/subagent/subagent-fork/README.md

@@ -31,12 +31,16 @@ See [`dsh-subagent-spawn`](../subagent-spawn/README.md) for the run lifecycle, m
 
 **Token effect**: Forking duplicates retained completed history into separate child requests; the child then accumulates its own tokens independently. Persona changes repeated prompt cost, filtering changes schema or generated SDK cost, and a first-turn fork has no inherited history.
 
+**KV Cache effect**: The child may reuse the inherited byte-identical prefix under the same provider and model. Persona, tool-filter, generated-SDK, or route changes may invalidate reuse before inherited history; later child history is append-only.
+
 ### Parent tool result, indirectly
 
 **What the model sees**: The parent receives only the child's own final output through `dsh-tool-subagent`, not the inherited prefix or intermediate work.
 
 **Token effect**: Parent input grows by one data-dependent final result retained until compaction.
 
+**KV Cache effect**: Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
 ## Known Limitations and Deferred Work
 
 - **Runs expose no `sendMessage`/`resume`** — the optional runtime capabilities are absent on in-process runs.

packages/subagent/subagent-inprocess/README.md

@@ -48,12 +48,16 @@ A clean turn that never commits the required structured value reports `error`; t
 
 **Token effect**: Child input is isolated from the parent and grows through the child's own steps. A persona changes repeated prompt text; filtering changes schema or generated SDK cost but not independently registered guidance.
 
+**KV Cache effect**: Independent of the parent request cache. The child's later history is append-only, while persona, tool-filter, generated-SDK, provider, or model changes establish a different child prefix.
+
 ### Structured-output system prompt, schema, and results
 
 **What the model sees**: A structured run adds the structured-output instruction below. It also adds a child-scoped `structured_output` definition with exact description `Report your final structured result. Call this exactly once, when your answer is complete; the arguments must match this tool's parameter schema exactly.` and the requested schema. This runtime-only definition is outside the generated shipped [tool package map](../../../docs/tool-catalog.md#tool-package-map). Success returns `Structured output recorded.`; a later call becomes ``Error: structured output already recorded: the run is complete, so `<tool>` is not executed``.
 
 **Token effect**: Fixed instruction and capability tokens are paid only by that child. Result text enters the child history, while the captured value alone becomes the parent result.
 
+**KV Cache effect**: Prefix-stable inside the child while the structured-output instruction and schema are unchanged. Changing the schema or capability may invalidate the child's cache from that early segment; results append in child and parent histories.
+
 #### Structured-output instruction
 
 ```markdown
@@ -66,12 +70,16 @@ When you have your final answer, you MUST report it by calling the `structured_o
 
 **Token effect**: Zero tokens on a successful start; only the failed parent tool call retains this text.
 
+**KV Cache effect**: Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
 ### Parent result, indirectly
 
 **What the model sees**: The driver extracts only the child's own last assistant output or captured structured value; seeded parent messages and intermediate child work do not become the result.
 
 **Token effect**: The parent receives one data-dependent result through the consumer; all other child tokens stay in the child session.
 
+**KV Cache effect**: Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
 ## Known Limitations and Deferred Work
 
 - **Runs expose no `sendMessage`/`resume`** — the optional runtime capabilities are absent on in-process runs.

packages/subagent/subagent-spawn/README.md

@@ -26,12 +26,16 @@ Spawn advertises `{ outputSchema: true, depthLimit: true, toolFilter: true, pers
 
 **Token effect**: The child pays for a new independent context and history; no parent-history tokens are duplicated. Persona changes this child's repeated prompt cost, while filtering changes its schema or generated SDK cost.
 
+**KV Cache effect**: Independent of the parent request cache. Child history grows append-only, while persona, tool-filter, generated-SDK, provider, or model changes establish a different child prefix.
+
 ### Parent tool result, indirectly
 
 **What the model sees**: Through `dsh-tool-subagent`, the parent receives only the child's final output or stop-reason error.
 
 **Token effect**: Parent input grows by one data-dependent result retained until compaction.
 
+**KV Cache effect**: Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
 ## Known Limitations and Deferred Work
 
 - **Runs expose no `sendMessage`/`resume`** — the optional runtime capabilities are absent on in-process runs.

packages/subagent/subagent-subprocess/README.md

@@ -41,6 +41,8 @@ A per-run isolated config directory for an external CLI child (the target of `CL
 
 Indirectly, through process-based subagent backends, whose child composition is constrained by credential scrubbing and isolated config directories.
 
+**KV Cache effect**: No direct invalidation; the named consumer owns any request-prefix changes.
+
 ## Known Limitations and Deferred Work
 
 - **The credential scrub is name-based** — only variables matching `KEY` / `SECRET` / `TOKEN` are removed; differently named secrets such as `PASSWORD` pass through unless the backend supplies a stricter environment.

packages/subagent/subagent/README.md

@@ -66,6 +66,8 @@ The model-facing tool collects synchronously by default: it awaits the child res
 
 Indirectly, through `dsh-tool-subagent`, which renders provider-specific schemas and foreground or generic-background results while child working context remains child-only.
 
+**KV Cache effect**: No direct invalidation; the named consumer owns any request-prefix changes.
+
 ## Known Limitations and Deferred Work
 
 - **Runtime steering and continuation are seam-only capabilities** — `sendMessage` and `resume` have no model-facing consumer in the current tool.

packages/subagent/tool-subagent/README.md

@@ -36,18 +36,24 @@ Foreground and background calls are exclusive. Children may share the parent's w
 
 **Token effect**: Fixed schema cost per parent request; each provider instance adds one schema.
 
+**KV Cache effect**: Prefix-stable while provider instances, names, descriptions, and schemas are unchanged. Provider registration lifecycle may invalidate parent reuse from the first changed tool definition.
+
 ### Foreground result
 
 **What the model sees**: The call retains the description and prompt. Success contains only the child's final text; other outcomes become `Error: <message>`. Intermediate child steps stay out of the parent.
 
 **Token effect**: The prompt and result remain in parent history until compaction; child working context remains in the child.
 
+**KV Cache effect**: Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
 ### Background task result
 
 **What the model sees**: Start returns exactly `started background subagent task <id>`. The generic task surface provides later status, final output, cancellation responses, and notices.
 
 **Token effect**: The acknowledgement is retained; final output enters parent history only when collected or injected.
 
+**KV Cache effect**: Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
 ## Known Limitations and Deferred Work
 
 - **Background runs expose final output only** — intermediate child steps stay in the child session.