[Feature Request] Cache Classifier: Shared Content Cache for Designated Folders Across Subagents

[Feature Request] Cache Classifier: Shared Content Cache for Designated Folders Across Subagents

Summary

Add a cache_classifier configuration primitive in settings.json that designates specific folders as shared cacheable content. When subagents spawn, they pull file content from these folders via a session-wide shared cache instead of re-reading from disk. This provides opt-in, content-based caching that is shared across parallel subagents — distinct from full conversation context inheritance.

Problem

When a parent agent loads a set of files (documentation, reference materials, guides, schemas, etc.) and then spawns multiple subagents that also need those same files, each subagent re-reads the files from disk independently. For workflows that spawn many parallel subagents that share a common reference set, this produces massive redundant input token costs.

Example scenario:

• Parent loads 60 reference documents (average 50KB each = 3MB total)
• Parent spawns 30 parallel subagents to perform independent tasks
• Each subagent needs access to the same 60 reference documents
• Current behavior: 30 × 60 file reads = 1,800 redundant file loads
• Input tokens: ~180M tokens (3MB × 30 subagents × token ratio)

The parent already paid to load these files. The content doesn't change during the session. Re-loading them per subagent is pure overhead.

Proposed Solution

A cache classifier configuration that designates specific folders whose content should be cached and shared across all agents in the session tree.

Configuration Example

{
  "cache_classifier": {
    "cached_folders": [
      "/path/to/project/reference_docs/",
      "/path/to/project/schemas/",
      "/path/to/project/style_guides/"
    ],
    "cache_scope": "session",
    "share_with_subagents": true,
    "invalidation": "file_mtime"
  }
}

Behavior

1. Parent agent reads a file from a designated cached_folder
2. Classifier tags the content with file path + hash/mtime and stores it in a session-wide cache pool
3. Subagent spawns and attempts to read the same file
4. Cache lookup finds the content by path + hash
5. Subagent receives cached content instead of disk read + token cost
6. Delta tokens only: subagent pays for its own prompt, tools, and task-specific content — not the cached reference material

Cache Invalidation

• File mtime tracking: if a cached file's modification time changes, the cache entry is invalidated and re-read
• Session-scoped: cache cleared at session end (configurable)
• Manual invalidation: optional CLI command to clear the cache

How This Differs From Existing Requests

Existing related issues (#12790, #38443, #15139, #39047) propose full conversation context inheritance — passing the parent's entire conversation history and tool outputs to subagents. That approach has significant tradeoffs: it can bloat subagent context with irrelevant content, complicate permission boundaries, and introduce unpredictable token costs.

This proposal is different:

| Dimension | Full Context Inheritance | Cache Classifier |
|-----------|-------------------------|------------------|
| Scope | All parent context | Designated folders only |
| Content | Conversation history + files | Files only |
| Control | Per-subagent flag | Per-folder configuration |
| Predictability | Variable (depends on parent state) | Deterministic (folder contents) |
| Token savings | High but unpredictable | High and predictable |
| Permission model | Inherits parent's permissions | Inherits folder access |
| Use case | Tight parent/child coupling | Shared reference libraries |

The cache classifier is opt-in, surgical, and content-based. The developer declares which folders contain shared reference material. The caching system handles the rest.

Use Cases

This feature benefits any workflow that:

• Spawns multiple parallel subagents
• Has a large shared reference set (documentation, schemas, style guides, type definitions)
• Needs deterministic input token costs
• Wants permission-scoped caching (cache only content from trusted folders)

Common examples:

• Multi-agent code generation pipelines with shared API documentation
• Parallel test runners with shared test infrastructure documentation
• Content generation systems with shared style guides
• Research workflows with shared citation databases
• Review agents examining multiple PRs against the same architecture docs

Why This Is Valuable

Cost predictability: Developers can calculate exact input token costs for subagent spawns. Cached content is paid for once, delta content is paid for per subagent.

Architectural clarity: Designating "this folder is shared reference material" is a clear architectural signal. It separates reference content from task-specific content.

Permission safety: The cached content is restricted to paths the developer explicitly designated. Subagents can't accidentally inherit sensitive parent context.

Scales with parallelism: The more subagents spawned, the greater the savings. A workflow spawning 30 parallel agents saves ~30x the reference-loading cost vs. no caching.

Alternative Approaches Considered

1. Pass file paths, not content: Subagent still has to read the file, still pays the input cost.
2. Compact files into smaller references: Reduces quality of reference material.
3. Sequential instead of parallel spawning: Defeats the purpose of parallelism.
4. Full context inheritance: Over-broad, non-deterministic, covered by existing requests.

The cache classifier is the minimal primitive that achieves the goal: shared content cache for designated folders, across all agents in a session.

Implementation Sketch

• Add cache_classifier section to settings.json schema
• At session start, scan cached_folders and build a path → hash index
• Intercept file reads in agents: if file path matches a cached folder AND hash is in cache, return cached content without disk read or token cost
• Share cache across subagent spawns via session-wide cache pool
• On file mtime change, invalidate entry and allow fresh read