[FEATURE]Version-pinned capability awareness: point the Skills pattern at the model's knowledge of its own host
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
A model's knowledge is frozen at its training cutoff, but Claude Code ships new capabilities weekly (the docs are full of "as of v2.1.196," "as of v2.1.198," "as of v2.1.212"). So the model driving the tool routinely does not know what the tool it is running inside can now do — and, worse, states stale beliefs confidently.
A wrong "that capability does not exist" is the costliest failure mode — more damaging than "I am not sure, let me check" — because the user (or the agent itself) acts on the false negative and never looks further.
This is a named problem in the agent literature: "knowledge freezing" / the "self-knowledge gap." It will not go away, because you cannot retrain a frontier model on every release. The fix has to be architectural, not "wait for the next model."
The proposed mechanism reuses machinery Claude Code already ships (Skills / on-demand context loading), so this is less "build a new system" and more "aim an existing one at self-knowledge."
Proposed Solution
\Turn Claude Code's own Skills pattern inward. Skills already exist to bridge frozen model knowledge and current capability — the agent sees short descriptions in its system prompt and loads full instructions on demand. That primitive has only ever been aimed at user/domain knowledge, never at the model's knowledge of its own host.
The harness already knows the exact running version (e.g. 2.1.217). Have it surface a version-pinned capability card: a concise, auto-loaded manifest (or a first-class claude-code-capabilities skill) covering the config surface the model otherwise cannot see — subagent/agent frontmatter fields (including effort, model, isolation), slash commands, settings keys, and recently shipped features for that version. Keep it cheap the Skills way: short descriptions in context, full detail loaded on demand.
Minimal viable version: inject a short "capabilities for vX.Y.Z" pointer right next to the version string the harness already provides, so the model knows what to check before asserting a capability is absent.
Alternative Solutions
- Inject the full docs into every system prompt. Too token-heavy; it bloats every session. The Skills load-on-demand pattern exists precisely to avoid this.
- Rely on the model to always read the current docs first. This is the de-facto status quo, and it fails exactly when it matters, because a confidently-wrong model does not know it needs to check.
- Keep filing per-feature requests (e.g. #77298 for per-invocation subagent effort). This treats symptoms one at a time; the model still will not know about the next shipped feature.
- A /whats-new or capability-introspection command the model can call on demand. A lighter cousin of the capability card; useful, but still requires the model to know to ask.
Priority
Medium - Would be very helpful
Feature Category
Configuration and settings
Use Case Example
The effort: subagent frontmatter field — "Effort level when this subagent is active. Overrides the session effort level." — exists and works today. Asked whether a subagent's effort could be controlled, the model (running inside Claude Code) confidently answered "no, you can't set it" — from inside the tool that has the field. Only an explicit "go read the current docs" surfaced the truth, at which point the model reversed itself. That doc round-trip, and the user prompt needed to trigger it, is exactly what a version-pinned capability card would make unnecessary.
Additional Context
Related symptom issues this sits above as the root-cause fix: #77298 (per-call effort parameter on the Agent/Task tool) and #43083 (configurable reasoning effort for subagents). Those are individual features the model did not know it had or could not reach; a capability card addresses the whole class rather than each instance.