[FEATURE] Per-system reference guides for Claude's built-in tools

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

Claude doesn't reliably know how its own built-in systems work — not because of reasoning failures, but because the specifications aren't provided at runtime. Evidence from real usage:

• AskUserQuestion (AUQ): When designing gate workflows, Claude was unaware that header and preview fields are internal metadata (never shown to the user), didn't understand the multi-gate rendering model, and had to reason through rendering behavior live — sometimes incorrectly.
• Plan Mode: Claude applies Plan Mode heuristics from training data rather than a specification, leading to inconsistent behavior across sessions.
• Task / Subagent system: How context is passed between tasks, what isolation guarantees exist, and what the parent agent can observe — all inferred rather than specified.

This produces real problems: Claude presents internal metadata fields as if they're user-visible content, gives users incorrect information about tool behavior, and consumes extra tokens reasoning through system behavior live during execution. System designers building on Claude Code can't trust that Claude correctly models the tools it's using.

Training data is not a solution to this. Tools change faster than training cycles. More importantly, knowledge baked into weights can't be audited or immediately corrected — a developer building on Claude Code can't verify what Claude "knows" about how AUQ works; they can only observe the outputs and correct errors after the fact.

Proposed Solution

Lightweight per-system reference guides, maintained by Anthropic, loaded on demand before Claude's first use of each covered system in a session.

Guide content per system (example — AskUserQuestion):

• Field visibility: which fields are shown to the user vs. internal metadata
• Interaction model: hard gate vs. soft prompt, what "waiting for response" means
• Rendering constraints: what markdown renders in which fields, character limits
• Common failure modes: what breaks, what produces unexpected output
• Multi-instance behavior: can multiple AUQs be queued, how does sequencing work

Delivery mechanism:

• Each guide is a small file (~1–3KB) loaded once per session on first use of that system — not injected into every context.
• Guides are versioned and updated when tool behavior changes, eliminating the lag between "tool updated" and "Claude knows about the update."
• Format: lightweight markdown that works in system prompts. No special rendering needed.

Scope: AUQ / gate system, Plan Mode, Task / Subagent system, and any tool with non-obvious field semantics or rendering behavior.

Alternative Solutions

• Training data updates: Tools change faster than training cycles, and trained knowledge can't be audited or immediately corrected when wrong. Reference guides can be updated immediately and take effect in the next session.
• Full documentation in every system prompt: High token cost paid even in sessions that never use the covered tool. On-demand loading avoids this entirely.
• Ad-hoc user correction: The current state — users notice when Claude models a tool incorrectly and correct it in chat. This shifts verification work onto the user, and incorrect outputs still occur before the correction is made.

Priority

High - Significant impact on productivity

Feature Category

Developer tools/SDK

Use Case Example

• Gate design: Claude reads the AUQ guide and knows header/preview are internal metadata — never presents them as user-visible fields, never designs around them as formatting tools.
• User questions: When a user asks "does AUQ support markdown in the question field?" — Claude answers from the spec, not from a training-data guess that may be outdated.
• Task system usage: Claude reads the Task guide and correctly models context isolation, so it doesn't assume parent-session variables are visible in subagents.
• Error diagnosis: When a gate behaves unexpectedly, Claude can reference the guide to distinguish "I designed this wrong" from "this is a tool behavior I wasn't aware of."

Additional Context

Related issues: #5092 (Claude Code's built-in self-knowledge — same core problem), #10346 (missing AUQ documentation — addressed as part of this proposal's scope).

Implementation could start with AUQ alone, which has the most acute and well-documented misunderstanding problem. This is structurally similar to how LSP servers provide hover documentation for library APIs — the tool author provides the spec, the consumer reads it at point of use. Claude should have the same access to specs for the tools it uses.