Skip to content

fix(effort): tolerate object schema from Claude Code 2.1.115+ - #491

Merged
jarrodwatts merged 2 commits into
jarrodwatts:mainfrom
zelinewang:fix/effort-object-schema-2.1.119
Apr 24, 2026
Merged

jarrodwatts merged 2 commits into
jarrodwatts:mainfrom
zelinewang:fix/effort-object-schema-2.1.119

Conversation

@zelinewang

Copy link
Copy Markdown
Contributor

Problem

Since Claude Code 2.1.115+, the statusline crashes on every tick with:

[claude-hud] Error: level.toLowerCase is not a function

when a user has display.showEffortLevel: true in their config. The crash
only appears after upgrading Claude Code from 2.1.114 (or earlier) to
2.1.115+.

Root cause

The original effort support (#471) was future-proofed for the case where
Claude Code would eventually expose the effort level via stdin JSON — but
because no schema existed yet, the type was guessed as a bare string:

effort?: string | null;

Claude Code 2.1.115+ actually added the field, but as an object:

"effort": { "level": "max" },
"thinking": { "enabled": true },
"fast_mode": false

resolveEffortLevel then passes the whole object into formatEffort, which
invokes level.toLowerCase() on what is actually a { level: "max" }
object — instant TypeError.

Evidence — live stdin dump from Claude Code 2.1.119 on macOS, Opus 4.7:

{
  "session_id": "…",
  "version": "2.1.119",
  "model": { "id": "claude-opus-4-7", "display_name": "Opus 4.7" },
  "effort": { "level": "max" },
  "thinking": { "enabled": true },
  "fast_mode": false,
  …
}

Fix

Accept both shapes (object with level string, or bare string) through a
tiny extractEffortString helper, and let any other truthy input fall
through to the existing --effort parent-process fallback rather than
throwing.

export type StdinEffortInput = string | StdinEffort | null | undefined;

export interface StdinEffort {
  level?: string | null;
  [key: string]: unknown;  // tolerate future additions like `budget`
}

The index signature keeps the type permissive — if Claude Code later adds
effort.budget or similar, no more breaking changes here.

Tests

Added 10 tests in tests/effort.test.js:

  • Object schema (Claude Code 2.1.115+ shape)
    • extracts { level: "max" } → renders ●
    • normalises uppercase level
    • handles all known levels inside objects
    • tolerates extra fields for forward-compat
    • falls through on missing / null / non-string level
  • Defensive handling (no crash)
    • numeric / boolean / array inputs fall through rather than throwing

Result:

baseline: 486 pass, 0 fail
after   : 496 pass, 0 fail  (no regressions)

End-to-end verified by feeding the captured stdin payload to a locally-built
dist/index.js:

$ cat /tmp/hud-stdin-dump.json | node dist/index.js
[Opus 4.7 ●max] ██░░░░░░░░ 15% | zane | …

Exit code 0, effort bracket renders correctly.

Notes

  • src/ only per CONTRIBUTING.md (CI rebuilds dist/ on merge).
  • Preserves backwards compatibility with the original PR feat: effort level display in model bracket #471 string shape
    in case any older Claude Code version still sends it or a user injects
    effort via another path.
  • The --effort parent-process fallback path is unchanged and still acts
    as a safety net when stdin gives us nothing usable.

Claude Code 2.1.115+ sends effort in stdin JSON as an object
({ "level": "max" }) rather than the bare string the original
design in PR jarrodwatts#471 was future-proofed for. That forward-guess
never materialised exactly as predicted, and the resulting type
mismatch crashes the statusline every tick:

    [claude-hud] Error: level.toLowerCase is not a function

Captured payload from Claude Code 2.1.119 (macOS):

    "effort": { "level": "max" },
    "thinking": { "enabled": true },
    "fast_mode": false,
    ...

Fix accepts both shapes via a small extractor, plus any
non-matching truthy type (numbers, booleans, arrays, empty
objects) falls through to the existing parent-process --effort
fallback rather than throwing.

Adds 10 tests covering:
  - object with level field (the real 2.1.115+ shape)
  - object with extra fields (forward-compat)
  - object missing/nullable level (fall through)
  - numeric / boolean / array inputs (no crash)

Baseline 486 pass -> 496 pass, 0 regressions.
@zelinewang
zelinewang requested a review from jarrodwatts as a code owner April 24, 2026 00:30
The previous JSDoc listed "object first, string second" but
`extractEffortString` checks `typeof value === 'string'` before
the object branch. Because the two input shapes are mutually
exclusive this does not cause a runtime bug, but a future reader
parsing the numbered list would draw the wrong conclusion about
dispatch order.

Swap items 1 and 2 and rename "Priority:" to "Resolution order:"
with an explicit cross-reference to the helper, so the comment
describes what the code actually does.

@jarrodwatts jarrodwatts left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Security, quality, and maintainability review cleared. Local full suite passed in an isolated worktree (496 pass, 1 skipped), and GitHub CI is green.

@jarrodwatts
jarrodwatts merged commit 8655e5b into jarrodwatts:main Apr 24, 2026
3 checks passed
prezis added a commit to prezis/claude-hud that referenced this pull request Apr 30, 2026
This fork adds a 4th resolution step to claude-hud's effort detection so
the badge works for users on Claude Code < 2.1.115 (no stdin.effort) and
for users who set effortLevel persistently in settings.json instead of
via --effort CLI flag.

Resolution priority (highest -> lowest):
  1. stdin.effort string (PR jarrodwatts#471 path, upstream)
  2. stdin.effort.level object (PR jarrodwatts#491, upstream, CC 2.1.115+)
  3. --effort CLI flag from parent process (upstream)
  4. settings.json effortLevel (NEW, this fork) -- reads from
     ${cwd}/.claude/settings.local.json, then settings.json, then
     ${CLAUDE_CONFIG_DIR:-~/.claude}/settings.json. Most-specific wins.

Behavior change: display.showEffortLevel default flipped false -> true
(this fork's whole purpose is to make effort visible by default).

Source changes (already in eb58786 via auto-commit hook): src/effort.ts
adds readSettingsEffort + cwd param; src/index.ts threads stdin.cwd;
src/config.ts flips default; tests/effort.test.js +8 tests for the
fallback (project-local > project > user precedence, malformed JSON,
non-string values, stdin still wins).

This commit: README banner explaining fork differences + CHANGELOG entry.

Tests: 519/520 pass (1 pre-existing skip).

Upstream-able: source changes are surgical and additive; PR candidate.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants