[FEATURE] Cache-eligible file reads: allow declared knowledge paths to be treated as stable context anchors

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

When I read a file via the Read tool — a design system reference, a style guide, a project knowledge page — that content lands in Messages as a transient tool result. It's re-counted as input tokens every time the same file is referenced in a session.

For stable reference material that doesn't change between reads, this is pure waste. Large knowledge libraries become economically painful to use repeatedly across a long session because there's no way to tell Claude Code "this file is stable, don't re-count it."

Proposed Solution

A knowledgePaths (or similar) key in settings.json that declares one or more directories as a knowledge library. Files under those paths would be:

• Loaded lazily — only on first read, not pre-loaded like CLAUDE.md
• Cached with a 1h TTL after first load, using the same prompt caching mechanism already in use for system-level content
• Served from cache on subsequent reads within the session, not re-billed as input tokens

Example config:

{
  "knowledgePaths": ["knowledge/", "projects/*/knowledge/"]
}

Alternative Solutions

The closest alternative is inlining files into CLAUDE.md via @filename references — that does get cached, but forces always-loaded rather than lazy. For a library of 30+ files, always-loading them all defeats the purpose. The other workaround is keeping knowledge files very small so re-reads are cheap, but that's working around the constraint rather than solving it.

Priority

High - Significant impact on productivity

Feature Category

Configuration and settings

Use Case Example

• I maintain a local knowledge library (~40 markdown files: design system docs, UX research, internal API references, writing style guide). During a working session I might reference 5–10 of these across 20–30 turns. Each reference re-reads the file and re-counts it as input tokens. A single 300-line design system doc referenced 8 times in a session costs as much in input tokens as reading it once should. With this feature, the first read caches it; turns 2–8 are cache reads at ~10% of the cost.

Additional Context

_No response_