Neurotokenv1.1.0

Neurotoken v1.1.0 shipped on GitHub on April 21, 2026. The headline feature is ceiling-rule mode, an opt-in dispatch strategy that lets Claude Code automatically downgrade to cheaper models on low-stakes work, while enforcing strict safety guards that prevent downgrade on anything that could go wrong.

If you run Opus globally and want to stop paying Opus prices for "fix this typo" prompts, this is the release that makes that possible without compromising the work that actually needs it.

What's in this release

• Ceiling-rule mode (NEUROTOKEN_MODE=active-ceiling): permits downgrade to cheaper models when scoring indicates the prompt is safely below the configured ceiling (default opus/max). Floor-rule mode remains the default.
• Strict safety guards: downgrade is never permitted when +auth, +deploy, +finance, +cross-project, or S=3 (critical stakes) fires.
• Expanded safety-modifier detection: 12 new patterns found via adversarial red-team testing: JWT, OAuth, RBAC, password, session, ship, promote, publish, release, edge function, Lambda, pricing, subscription, checkout.
• Improved scoring for terse prompts: imperative-extraction patterns now catch architectural commands like "make X independent", "extract X into Y", "migrate X to" that previously under-scored.
• High-water mark fixes: absolute 10-minute expiry, fresh-task gating, user-override bypass. Stale HWM no longer leaks across unrelated tasks.
• 183 tests across 33 suites, 181 passing, 2 skipped for documented natural-language edge cases, 0 failures. Green on Node 20, 22, and 24.

The backstory

Neurotoken started as a manual habit. I was writing feedback memories for Claude Code (notes like "label plan steps [Opus]/[Sonnet], parallelize Sonnet batches for mechanical work") and realized I was doing the same triage every time. Score the prompt, pick the tier, move on. That's automatable judgment, not creative judgment.

So I built v1.0 as a pure shadow logger. No actuation, no dispatch changes, just a hook that scored every prompt and wrote the annotation to a log file. It ran in shadow mode for 8 days across my real projects. I could review the logs each morning and see where the grader agreed with my gut and where it didn't.

Only after the scoring accuracy held up on real prompts (not contrived test cases, but actual "fix this import" and "redesign the auth module" work) did I flip the switch to ceiling-active. The principle: validate before actuating. If you can't trust the scores in read-only mode, you definitely can't trust them making decisions.

What almost broke this

The asymmetric cost problem nearly sank ceiling mode. Under-scoring routes a complex prompt to Haiku, Haiku fails, you re-run on Opus anyway, and you've now paid for both calls plus lost the time. Over-scoring just means you spent a few extra cents on a typo fix. The failure costs aren't symmetric, so the scoring engine has to be biased toward caution: it's fine to over-score occasionally, but under-scoring even once on the wrong prompt is expensive.

The adversarial red-team found 12 modifier gaps that could have caused unsafe downgrades. Prompts mentioning JWT rotation, OAuth flows, RBAC policies, session management, and deployment pipelines were slipping through without triggering safety guards. Each one represented a real scenario where a downgrade could produce subtly wrong output on high-stakes work. Those patterns got backfilled into the safety-modifier dictionary before ceiling mode shipped.

What I learned

The matrix asymmetry turned out to be the most transferable idea in this project. Any system that routes work to different tiers, whether that's model selection, server pools, or worker queues, has the same shape: the cost of routing too high is linear (you overpay), but the cost of routing too low can be catastrophic (you get a wrong answer, a failed deploy, a broken auth flow). The optimal bias is always toward the expensive-but-safe option.

This maps cleanly onto circuit breakers, retry policies, and auto-scalers. A circuit breaker that opens too eagerly is annoying; one that opens too late lets cascading failures through. The same asymmetry, the same bias. I suspect any routing or load-balancing system with meaningfully different failure modes benefits from this kind of intentional skew in its decision boundary.

What a neurotoken is

A neurotoken is a scoring annotation that Neurotoken attaches to every prompt before Claude Code processes it. It looks like this:

[neurotoken] C=2 S=1 → sonnet/high (+novel, HWM=opus/med@3m)

That line tells you: complexity 2 (medium), stakes 1 (moderate), recommended tier is sonnet/high, the +novel modifier fired because the prompt references unfamiliar patterns, and the high-water mark from 3 minutes ago was opus/med.

The annotation is injected into the hook output, not the terminal. Claude Code reads it and adjusts its thinking budget accordingly.

How ceiling-rule mode works

In the default floor-rule mode, Neurotoken can only escalate. If your agent runs on Sonnet and Neurotoken scores a prompt as opus-tier, the annotation tells Claude Code to think harder. But it never tells Sonnet to think less; the floor is always the agent's configured default.

Ceiling-rule mode inverts this. If you run Opus globally and Neurotoken scores a prompt at haiku/med, ceiling mode permits the downgrade. The key constraint: safety guards are absolute. Any prompt that triggers +auth, +deploy, +finance, +cross-project, or scores S=3 on the stakes axis stays at the ceiling regardless of complexity.

The under-scoring problem

Ceiling mode created a new failure mode: if the scoring engine misclassifies a complex prompt as simple, the prompt gets routed to Haiku and fails. This is worse than over-scoring (which just costs more money).

The v1.1 fix adds imperative-extraction patterns for terse architectural prompts. Commands like "make the auth module independent" are short but high-complexity, and the old scoring engine saw few words and scored low. The new patterns detect imperative verbs paired with architectural nouns and score accordingly.

The scoring matrix

Every prompt maps to a cell in a 4x4 matrix. The matrix is intentionally asymmetric: high stakes with low complexity still routes to Opus, because getting a simple thing wrong in production is worse than overthinking a hard question in a sandbox.

The scoring pipeline runs in six stages: normalize the prompt, score complexity and stakes independently against signal dictionaries, bucket into 0-3, look up the matrix cell, apply modifiers (escalation capped at +2, de-escalation at -1), check the high-water mark, and apply any user override ("think harder", "quick answer").