[FEATURE] Expose Claude Code Cognitive Telemetry States via API

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

I'm building advanced Claude Code extensions that need to understand Claude's cognitive state during execution to make intelligent decisions about when to intervene, supplement context, or route tasks elsewhere.
The Core Problem:
Claude Code displays cognitive telemetry states during inference ("Channelling...", "Synthesizing...", "Discombobulating..."), but these states are not exposed programmatically through the hook system or any API. This creates a "black box" problem where extension developers can see outputs but can't understand why Claude is struggling or when it needs help.

Why This Matters:
Claude's training data inevitably lags reality—new APIs, updated libraries, and evolving best practices mean Claude will encounter knowledge gaps. Currently, there's no way for hook-based systems to detect these gaps and proactively provide current documentation or context. We can only react to failures after they've occurred.

My Workflow:
I'm building meta-cognitive supervision systems that:

Monitor Claude's cognitive state in real-time
Detect when Claude encounters uncertainty or knowledge gaps
Proactively inject current documentation or route to specialized knowledge sources
Prevent failures before they manifest rather than recovering after

Without programmatic access to cognitive telemetry, I'm forced to use crude heuristics, semantic usage patterns, error rates) which are far less reliable than Claude's own internal assessment of its certainty.

Proposed Solution

Ideal User Experience:

1. Hook System Enhancement

Expose cognitive telemetry through the existing Claude Code hook system:

// Example hook implementation
export const hooks = {
onCognitiveStateChange: async (state: CognitiveState) => {
// state.name: "discombobulating" | "channelling" | "synthesizing" | etc.
// state.confidence: 0.0-1.0
// state.contextNeeds: ["api_docs", "domain_knowledge", etc.]

if (state.name === "discombobulating" && state.confidence < 0.5) {
// Pause execution, inject current docs, or route to supervisor
return {
action: "inject_context",
context: await fetchCurrentDocs(state.contextNeeds)
};
}
}
};

2. Minimal Documentation

Provide official reference documentation covering:

State Vocabulary Table

| State Name | Cognitive Description | Typical Confidence Range | Context Needs |
|------------|----------------------|-------------------------|---------------|
| channelling | High-confidence retrieval | 0.8-1.0 | Existing knowledge sufficient |
| synthesizing | Cross-domain bridging | 0.6-0.9 | May benefit from domain expertise |
| discombobulating | High entropy/uncertainty | 0.2-0.6 | Missing context or contradictory info |
| ... | | | |

API Surface

getCurrentCognitiveState(): CognitiveState

Query current state

onCognitiveStateChange(callback)

Subscribe to state transitions

getCognitiveHistory(): CognitiveState[]

Analyze state transitions over time

3. Integration Points

Make this available through:

• Hook system (for real-time intervention)
• CLI flags (--expose-telemetry for debugging)
• MCP server interface (for external tooling)

Alternative Solutions

What I've Considered:

1. Confidence Metrics Only

Instead of full state vocabulary, expose a simple confidence score (0.0-1.0). This is simpler but loses valuable semantic information about why confidence is low.

1. Binary Uncertainty Flag

Just expose a boolean "needs_help" signal when Claude detects knowledge gaps. Very simple to implement but provides minimal guidance on what kind of help is needed.

1. Response Time Heuristics

Use response latency and token generation patterns as proxy for uncertainty. Currently using this workaround but it's unreliable—slow responses might indicate deep thinking, not uncertainty.

1. Error Rate Analysis

Detect uncertainty by tracking syntax errors, test failures, and retries. This is reactive rather than proactive—the damage is already done by the time we detect it.

1. Scraping UI Text

Parse the visual telemetry states from terminal output. Extremely brittle, breaks with any UI changes, and feels like a hack rather than a supported integration.
Why Current Workarounds Are Insufficient:
All of these approaches are indirect proxies for information Claude already has internally. They're less accurate, more fragile, and miss opportunities for early intervention.

Priority

Critical - Blocking my work

Feature Category

API and model interactions

Use Case Example

Scenario: Building a Feature with Zig 0.16
Context: I'm using Claude Code to build a Zig application. Claude was trained on Zig 0.13, but I'm using 0.16 (released after training cutoff). There are breaking API changes.
Step-by-Step Workflow:

I ask Claude: "Implement a HTTP client using Zig's std.http"
Without Telemetry (Current Experience):

Claude confidently writes code using 0.13 API
Code fails to compile with cryptic errors
I manually realize version mismatch
I provide current documentation
Claude rewrites implementation
Time wasted: 10-15 minutes - hour (depending on how claude tackles the problem), frustration level: high

With Telemetry (Proposed Experience):

Claude begins generating code
My hook detects cognitive state: {name: "channelling", confidence: 0.85, contextNeeds: ["zig_stdlib_api"]}
Hook system checks: "Is my Zig stdlib knowledge current for this project?"
Detects version mismatch (local: 0.16, training: 0.13)
Proactively injects current API docs before Claude commits to wrong API
Claude adjusts approach mid-generation using current docs
Code compiles first try
Time saved: hours, frustration level: zero
Alternative Scenario - Deep Uncertainty:

Claude encounters genuinely novel pattern
State changes to: {name: "discombobulating", confidence: 0.35, contextNeeds: ["domain_expertise", "architectural_guidance"]}
My hook detects low confidence
Routes question to supervisor AI (Gemini with architecture expertise)
Supervisor provides high-level guidance
Hook injects guidance back to Claude
Claude resumes with clearer direction
Result: Complex problem solved through AI collaboration rather than Claude struggling alone

Real Impact
This pattern has already proven valuable in my prototype (using UI scraping workaround):

faster completion of tasks involving new APIs
reduction in Claude "giving up" or producing placeholder code
Measurably higher code quality on first attempt

Additional Context

Similar Features in Other Tools
OpenAI Assistants API:

Exposes function calling state transitions
Provides "reasoning" output for o1 models
Allows inspection of tool usage decisions

Anthropic Messages API:

Exposes thinking tokens (in extended thinking mode)
Shows reasoning process, but only in final output, not real-time

What Makes This Request Different:
Claude Code already generates cognitive telemetry internally—this is just about exposing it programmatically for extension developers.
Technical Considerations
Stability Concerns:
I understand internal state names might change between versions. This is fine—I'd prefer:

Clear versioning of the telemetry schema
Deprecation warnings when states change
A "stable subset" of guaranteed states (even if just high/medium/low confidence)

Privacy/Safety:
Cognitive telemetry should respect existing privacy guarantees:

No exposure of training data or internal model details
States should be semantic ("uncertain") not mechanistic ("attention_pattern_X")
Hooks can opt-in to telemetry exposure

Performance:
State transitions are already being computed for UI display—exposing them to hooks should have minimal overhead.
Links & Resources
My Public Work:

GitHub: https://github.com/quantum-encoding
Website: quantumencoding.io
Aegis Shield Project: aegis.quantumencoding.io

Relevant Research:

Meta-cognitive AI systems (cognitive monitoring in AI)
AI uncertainty quantification for human oversight
Multi-agent collaboration frameworks

Offer to Collaborate
Happy to:

Sign NDA for technical details
Share my prototype implementation
Provide feedback on API design
Beta test any experimental implementations
Write documentation/examples for other developers

Why This Aligns with Anthropic's Mission
Transparent cognitive telemetry is a powerful tool for AI alignment and human oversight. When developers can see when and why Claude is uncertain, they can:

Build better guardrails
Provide targeted supervision
Prevent errors before they manifest
Understand AI limitations in real-world scenarios

This makes Claude Code more steerable, more reliable, and more trustworthy—core tenets of Anthropic's safety mission.

Thank you for considering this feature request! I believe this would unlock significant ecosystem value and enable a new generation of intelligent Claude Code extensions.