@litfamily/litclaude 1.0.21 → 1.0.23

package/docs/hooks.md

@@ -102,7 +102,7 @@ silent no-op for callers that still invoke it directly.
 
 | Event | Runner | Purpose |
 | --- | --- | --- |
-| `SessionStart` | `plugins/litclaude/bin/litclaude-hook.js session-start` | Runs the bounded foreground automatic-update barrier on a fresh session, discovers repo-local rule files, names the newest valid `plans/<slug>.md`, and on `source: compact` spends one of two durable re-injection reservations at reduced caps and, with automatic handoff on, reloads the fresh handoff once. |
+| `SessionStart` | `plugins/litclaude/bin/litclaude-hook.js session-start` | Runs the bounded foreground automatic-update barrier on a fresh session (or starts the detached version-cache refresh when the cache is stale), discovers repo-local rule files, names the newest valid `plans/<slug>.md`, and on `source: compact` spends one of two durable re-injection reservations at reduced caps and, with automatic handoff on, reloads the fresh handoff once. |
 | `UserPromptSubmit` | `plugins/litclaude/bin/litclaude-hook.js user-prompt-submit` | Detects prompt routes and injects workflow context; independently delivers static rules not already recorded for this session; with `LITCLAUDE_JEV=1` and `TYPESAFE_API_KEY` set, adds at most one Jev skill hint line to an unrouted turn; answers the exact prompts `lit-handoff auto on <percent>`, `lit-handoff auto off` and `lit-handoff auto status` by changing or reporting the automatic handoff setting. |
 | `PreToolUse` | `plugins/litclaude/bin/litclaude-hook.js pre-tool-use` | Enforces semantic action/root grants before Write, Edit, MultiEdit, NotebookEdit, Bash, Agent, and bounded read tools execute; denies supported reader-facing text writes with a humanizer block-tier finding. |
 | `PostToolUse` | `plugins/litclaude/bin/litclaude-hook.js post-tool-use` | Names the post-edit checks the edit actually earned, injects any glob-scoped rule matching the edited paths, and checks successfully created DOCX/PPTX/PDF files for humanizer findings, including paths reported by Bash output. |
@@ -182,8 +182,27 @@ commands. `--no-auto-update`, `LITCLAUDE_NO_AUTO_UPDATE`,
 `NO_UPDATE_NOTIFIER`, and `LITCLAUDE_NO_UPDATE_CHECK` disable it. CI, JSON,
 dry-run, non-TTY management commands, import, and tool surfaces remain no-op;
 the host-owned SessionStart hook is the lifecycle exception to the TTY check.
-The detached registry cache refresh described in the update-notifier section is
-advisory and never performs an install.
+
+SessionStart also keeps that cache fresh. When the cache is missing or older than
+24 hours, and no attempt was recorded in the last 24 hours, the hook records the
+attempt and starts a detached child
+(`plugins/litclaude/lib/automatic-update-refresh.mjs`) that makes one GET for the
+package's latest version, with a 3-second limit, no redirect and a 64 KiB cap. The
+hook does not wait for it. The child writes `latest.json` only if its attempt still
+owns the cache, and never installs anything. A cache file that is not LitClaude's own record, such as another package's, is left untouched; the next fresh session applies the
+version through the transaction above. The request goes to the registry in
+`npm_config_registry` when that is a plain origin, the same registry the install
+uses, and to `registry.npmjs.org` otherwise. Every opt-out above stops the request
+too. Offline, the attempt fails quietly and the next try waits a day.
+
+Before installing, the hook reads `installed_plugins.json` under the Claude home. If
+the registered LitClaude version is already the cached version or newer, it skips the
+install. A long-lived Claude Code process keeps running the hook from the version
+folder it started with, so without this check every new session in that process
+would install the same version again. The hook also skips a version whose latest receipt
+under `update-notifier/automatic/` is `rolled-back` or `failed` and less than 24 hours old,
+so a version that just failed is retried once a day, not on every session. A newer version
+is tried at once.
 
 ### Jev skill hint (optional)
 
@@ -262,9 +281,9 @@ through. The `.litclaude` and `.litclaude/jev` folders must be real folders too:
 is a symlink, the hint reads and writes nothing there, sends no request, and shows no hint or note. Because `TYPESAFE_API_KEY` is exported in the shell that starts Claude Code, the
 agent's own tools can read it too; use a key dedicated to this feature, with a low spend limit.
 `litclaude doctor` prints `Jev skill hint: off`, `Jev skill hint: on`,
-or `Jev skill hint: flag on but TYPESAFE_API_KEY missing`. The GitHub README shows each
+or `Jev skill hint: flag on but TYPESAFE_API_KEY missing`. The Jev page shows each
 visible state in sample output under
-[What you will see](https://github.com/wjgoarxiv/litclaude#what-you-will-see). The offline regression tests,
+[What you will see](https://github.com/wjgoarxiv/litclaude/blob/main/docs/jev.md#what-you-will-see). The offline regression tests,
 which replace `fetch` in the real hook process, live in `test/jev-skill-hint.test.mjs`.
 
 ## Automatic handoff
@@ -320,6 +339,113 @@ The pieces, in the order they run:
 project it runs in. The model still has to follow the block reason to write the file; the hook
 can require nothing more than that.
 
+## The LIT band (Claude Code mod)
+
+From Claude Code 2.1.287 a plugin can ship a mod: a hooks module that draws inside Claude Code
+itself. LitClaude's is `plugins/litclaude/hooks/lit-mod.mjs`, named under `modules` in
+`hooks/hooks.json` next to the settings hooks above. It installs with the plugin and needs no
+setup. The status line stays as it is; the band adds a live layer above the prompt.
+
+From the first prompt to the end of the session a LIT card sits above the prompt. It keeps the
+same four rows whether LitClaude is working or idle, and takes the status line's accent
+(`LITCLAUDE_HUD_ACCENT`, read from the installed status line command), so the card and the
+status line read as one family:
+
+```
+╭─ [🔥 LIT] · lit-loop ─────────────────────────── WORK ● ─╮
+│ ● PLAN ━━ [WORK] ━━ ○ REVIEW              goal ██░░░ 2/5 │
+│ skills [⚡ lit-plan] [⚡ litresearch] [↯ lit-docx]        │
+╰─ ctx 42% ▰▰▱▱▱ · 5h 31% · git main ──────────────────────╯
+```
+
+The brackets stand for the ends of filled pills: rounded caps from the icon font with `nerd`
+glyphs, one cell of the pill's colour with `basic`. The brand is a pink pill, the active phase
+and the skills of this request are pills on the accent with dark text, and skills from earlier
+requests are muted grey pills.
+
+- The top edge names the discipline the prompt hook ignited (the last one, dimmed, while the
+  session is idle; `ready` before any) and, on the right, the current phase: `WORK ●`, `idle`,
+  or `DONE ✓` during the finish.
+- The phase row lights `PLAN ━━ WORK ━━ REVIEW` from the start-work plan, the litgoal goal and
+  the discipline (the active phase as a pill, done phases `●`, the rest `○`), and on its right shows a pink-to-cyan progress bar with the checked tasks or
+  passed criteria (`goal ✓ 5/5` once a goal is met), the number of live subagents, the autoloop
+  count with the time left in its 30-minute budget, and `ctx 76% → 80%` when the context is
+  within five points of the auto-handoff percent.
+- The chips row shows each LitFamily skill that fired as a pill: a Skill tool call naming a LitClaude
+  skill, a typed `/litclaude:<name>`, or bare `lit` routing seen through the ignition record.
+  A skill fired in the current request is bright, with a short light passing over its name as
+  it arrives; when the turn completes it dims into the `recent` list, and a new firing brightens
+  it again. Chips follow a dim `skills` label; those that do not fit collapse into a muted `+N`. Skills of other plugins never get a chip.
+  With no chip yet, the row shows the next task while work runs, or how to start (`lit <task>`)
+  while idle.
+- The bottom edge carries the live figures from the status line: context fill, the five-hour
+  rate window and the Git branch (read from `HEAD`, across a linked worktree).
+- A notice takes the chips row for a few seconds, with a toast, when a gate fires: lit-plan not
+  saved, interface probe pending or failed, motion gate, context near the auto-handoff percent,
+  auto-handoff fired. The completion moment takes it when the last task is checked, the work
+  completes or the goal is met: a light passes over the brand, embers scatter, and `COMPLETE`
+  shows for about a second.
+- Amber or red when something needs attention: a lane quiet for more than 10 minutes turns the
+  border amber and puts `⚠ <lane> quiet for 12m` on the bottom edge; a failed interface probe
+  turns it red.
+
+The card is the terminal's width up to 80 columns and every row is fitted to it, with Hangul and
+emoji counted as two cells. Nothing wraps: on a narrow terminal the Git branch goes first, then
+the rate window, the lanes, the autoloop count and the long phase labels (`P ━ W ━ R`).
+
+The spinner gains ` · <discipline> · n/m` after its ellipsis. `/lit-evidence` opens a pane with
+three tabs (keys `1`, `2`, `3`): the goal's criteria with their last evidence, blockers and the
+newest litgoal ledger entries; the lanes; and the gates.
+
+Motion: entrances pop in 60 ms apart with a slight overshoot (160 ms each), fills and colour
+changes ease in and out (300 ms and 140 ms), notices slide in over 220 ms and leave over 150 ms,
+a chip's arrival light runs 400 ms (a plain fade under `subtle`, nothing under `off`), and the
+finish lasts at most 1.2 s. The band's `Client` element animates on Claude Code's frame
+clock only while something moves and stops its timer as soon as everything settles. In Claude
+Code 2.1.292 a terminal row whose only change is a non-ASCII glyph is not repainted, so every
+moving part changes ASCII text or colour: bar cells are coloured spaces, embers are ASCII sparks,
+a chip's light moves over its ASCII name, and a glyph swaps only together with its words.
+
+Options, in `/config` under LitClaude (stored in `pluginConfigs`):
+
+| Option | Values | Default |
+| --- | --- | --- |
+| `motion` | `full`, `subtle` (no overshoot, shimmer or embers, shorter), `off` (final frames only) | `full` |
+| `glyphs` | `auto` (Nerd glyphs when the icon font is installed), `nerd`, or `basic` | `auto` |
+| `band` | `always` (the whole session, idle included), `auto` (only while work is active or a skill of this request is lit), `off` | `always` |
+
+Unknown values fall back to the default. The fields are plain strings with no `options` list on
+purpose: Claude Code 2.1.270 and older refuse to load a plugin whose `userConfig` has one, and
+that would take every LitClaude hook down with it. Nerd glyphs reach only the terminal; the
+desktop app and the other surfaces always get the basic set.
+
+The icons on `nerd` (the rounded pill caps U+E0B6 and U+E0B4, the chip bolt and the branch mark)
+come from a Nerd Font. `litclaude-ai install
+--icon-font`, or a Yes to the install question (default No), adds the symbols-only Nerd Font,
+Symbols Nerd Font Mono (MIT), to the per-user font folder (`~/Library/Fonts` on macOS,
+`~/.local/share/fonts` on Linux, then `fc-cache -f` if present; on Windows it prints how to
+install it by hand). Your terminal font stays as it is: most macOS terminals take the missing
+icons from the installed font through system font fallback, and the installer prints one line for
+your terminal (from `TERM_PROGRAM`) in case it does not. The archive is the pinned Nerd Fonts
+release asset, refused unless its SHA-256 matches; `LITCLAUDE_ICON_FONT_SOURCE` names an offline
+copy of the same archive. The licence goes next to the font, a manifest under `~/.litclaude`
+records the two files, `uninstall` removes only those (and only while unchanged), and `doctor`
+prints `ICON_FONT:`. With `glyphs` on `auto`, the band checks those font folders by stat at session
+start and says what it decided on the `/lit-evidence` gates tab.
+
+The mod is read-only. It reads LitClaude's own state, the Git `HEAD` of the working directory and
+the merged settings (for the status line's accent) and nothing else: the ignition record in the
+per-user temp folder, `.litclaude/boulder.json` (found the way the hooks find it, across a
+linked worktree), and under the outermost Git root's `.litclaude/` the litgoal goal, autoloop
+counter and ledger, the lit-plan, interface-probe and motion turn records, and the auto-handoff
+settings and session record. Each file must be a regular file under its size cap that resolves
+exactly where its path says, so a symlinked file or state folder is skipped. It writes nothing,
+starts no process, uses no network and calls no model. Its pure parts live in
+`plugins/litclaude/lib/mod/` and are tested under Node.
+
+On Claude Code releases before 2.1.287 the `modules` key is ignored and every settings hook runs
+as before; there is no band.
+
 ## Bounded-authority start-work lifecycle
 
 The hook and CLI share `plugins/litclaude/lib/start-work-lifecycle.mjs`.

package/docs/privacy.md

@@ -11,8 +11,8 @@ transcript, model request, or diagnostic report contains no sensitive informatio
 | Surface | Destination and data | Controls and limits |
 | --- | --- | --- |
 | Package installation | npm and its configured registry retrieve package metadata and package bytes; ordinary package-manager connection metadata is visible to those services. Global installation can run LitClaude's postinstall setup. | `LITCLAUDE_AUTO_INSTALL=0` or `LITCLAUDE_POSTINSTALL_SKIP=1` skips automatic plugin/HUD setup. It does not stop npm from fetching the package. |
-| Update notice | Interactive `install`, `update`, and `doctor` can schedule an HTTPS GET to `registry.npmjs.org` for the package's latest-version metadata. The request identifies the package and sends an update-notifier user-agent; the request body does not contain project files or prompts. | Attempts are throttled using a 24-hour local cache. `NO_UPDATE_NOTIFIER` or `LITCLAUDE_NO_UPDATE_CHECK` disables the notice/check path, even when the variable is empty. CI, JSON, dry-run, and non-TTY management calls are gated. |
-| Automatic update | An eligible cached newer version can trigger npm to fetch and run the installer, then doctor. This can occur on `SessionStart` or interactive management commands. | `LITCLAUDE_NO_AUTO_UPDATE` disables automatic installation but leaves update checks eligible. `LITCLAUDE_NO_UPDATE_CHECK` or `NO_UPDATE_NOTIFIER` disables both paths. SessionStart is a piped host hook, so it does not use the management TTY requirement. |
+| Update notice | Interactive `install`, `update`, and `doctor` can schedule an HTTPS GET to `registry.npmjs.org` for the package's latest-version metadata. A fresh Claude Code session (`SessionStart`) does the same in a detached background process when the cached result is missing or older than 24 hours; that request goes to `npm_config_registry` when it is set to a plain origin. The request identifies the package and sends an update-notifier user-agent; the request body does not contain project files or prompts. | Attempts are throttled using a 24-hour local cache. `NO_UPDATE_NOTIFIER` or `LITCLAUDE_NO_UPDATE_CHECK` disables the notice/check path, even when the variable is empty. CI, JSON, dry-run, and non-TTY management calls are gated. |
+| Automatic update | An eligible cached newer version can trigger npm to fetch and run the installer, then doctor. This can occur on `SessionStart` or interactive management commands. | `LITCLAUDE_NO_AUTO_UPDATE` disables automatic installation and the SessionStart check that feeds it, but leaves the interactive update notice eligible. An install is skipped when Claude Code already lists that version or a newer one. `LITCLAUDE_NO_UPDATE_CHECK` or `NO_UPDATE_NOTIFIER` disables both paths. SessionStart is a piped host hook, so it does not use the management TTY requirement. |
 | Jev skill hint | Off by default. With `LITCLAUDE_JEV=1` and your own `TYPESAFE_API_KEY`, the `UserPromptSubmit` hook sends one HTTPS POST per eligible prompt to `api.typesafe.ai`. The body holds the prompt truncated to 2,000 characters with home paths, e-mail addresses, and token-shaped strings redacted, plus the list of LitClaude skill names and descriptions. Anything in the prompt without a token shape, such as a hostname, a customer name, or a password not written as `password=…`, is sent as written. No files, tool output, or history are sent. TypeSafe bills the request to your account (about $0.04 per million input tokens). | Unset `LITCLAUDE_JEV` to turn it off. Slash commands, routed prompts, and prompts that name a skill are never sent. Each request has a 1.5-second timeout, no retry, no redirect, and a per-session cap of 200. Because `TYPESAFE_API_KEY` is exported in the shell that starts Claude Code, the agent's own tools can read it; use a key dedicated to this feature, with a low spend limit. |
 | Public source reader | `litclaude public-read` resolves DNS and sends HTTP(S) GET requests to the supplied public URL and validated redirects. Plain search text becomes a query to `duckduckgo.com/html/`. Requests use a LitClaude user-agent and Accept header. The destination sees the requested path and query, plus normal connection metadata. | The reader rejects credential-bearing URLs and private-network targets, revalidates redirects, and stops at detected authentication/paywall barriers. It does not use a browser login or cookie jar. Redacting a URL in returned evidence does not remove query values from the actual request. |
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@litfamily/litclaude",
-  "version": "1.0.21",
-  "description": "Claude Code-native workflow distribution.",
+  "version": "1.0.23",
+  "description": "Claude Code plugin: add lit to a prompt and Claude plans, tests, checks and reviews the work, then leaves a handoff for the next session.",
   "type": "module",
   "bin": {
     "litclaude-ai": "bin/litclaude-ai.js",
@@ -82,9 +82,19 @@
   },
   "keywords": [
     "claude-code",
+    "claude-code-plugin",
+    "claude",
     "plugin",
     "ai-agents",
-    "orchestration"
+    "agent-workflow",
+    "orchestration",
+    "planning",
+    "code-review",
+    "research",
+    "tdd",
+    "context-handoff",
+    "korean",
+    "office-documents"
   ],
   "author": "LitClaude contributors",
   "license": "MIT",

package/plugins/litclaude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "litclaude",
   "description": "Claude Code-native workflow plugin with a bounded-authority start-work lifecycle.",
-  "version": "1.0.21",
+  "version": "1.0.23",
   "author": {
     "name": "LitClaude contributors"
   },
@@ -13,5 +13,25 @@
   "mcpServers": "./.mcp.json",
   "lspServers": "./.lsp.json",
   "displayName": "LitClaude",
-  "defaultEnabled": true
+  "defaultEnabled": true,
+  "userConfig": {
+    "motion": {
+      "type": "string",
+      "title": "LIT band motion",
+      "description": "How the band above the prompt moves: full, subtle (no overshoot, shimmer or embers) or off.",
+      "default": "full"
+    },
+    "glyphs": {
+      "type": "string",
+      "title": "LIT band glyphs",
+      "description": "auto uses the icon font when it is installed (litclaude-ai install --icon-font); nerd always; basic works with any font.",
+      "default": "auto"
+    },
+    "band": {
+      "type": "string",
+      "title": "LIT band",
+      "description": "When the LIT card shows above the prompt: always (the whole session, idle included), auto (only while LitClaude work is active or a skill of this request is lit) or off.",
+      "default": "always"
+    }
+  }
 }

package/plugins/litclaude/bin/litclaude-hook.js

@@ -744,11 +744,13 @@ const hasUiModeIntent = (normalized) => hasInterfaceModeWord(normalized) && uiSu
 // ("the report says", "deck of cards", "문서 참고"). Hangul terms are bare substrings for the
 // reason given above, except 덱, which would match inside 인덱스 and so needs a non-Hangul
 // neighbour. Code documentation and tool reports are excluded by name: a README, API docs,
-// a docstring, a bug, test, coverage or error report are not Word files.
+// a docstring, a bug, test, coverage or error report are not Word files. A Markdown file is
+// excluded only when it is a named project document or sits under docs/; any other `.md` is
+// usually the source of the deck or report ("turn notes.md into slides").
 const officeVerb = /\b(?:make|making|made|create|creating|write|writing|draft|drafting|prepare|preparing|build|building|generate|generating|produce|producing|put\s+together|turn\b.*\binto|compile)\b|만들|만드|작성|써\s?줘|써\s?주|써서|써봐|쓰고|정리해|정리하|준비|초안|뽑아|짜\s?줘|구성해/u;
 const slideNoun = /\b(?:slides?|slide\s?deck|deck|presentation|pptx?|powerpoint|keynote)\b|발표|슬라이드|피피티|파워포인트|(?<![가-힣])덱(?![가-힣])|(?<![가-힣])덱을|(?<![가-힣])덱으로/u;
 const documentNoun = /\b(?:reports?|docx|doc|documents?|word\s+(?:doc(?:ument)?|file)|ms\s?word|white\s?papers?|proposals?|memos?)\b|보고서|리포트|기획서|제안서|계획서|문서|워드|백서/u;
-const codeDocumentation = /readme|changelog|contributing|api\s?(?:문서|docs?\b|reference)|docstrings?|jsdoc|javadoc|주석|\.md\b|\bdocs\/|\b(?:bug|test|coverage|error|crash|lint|issue|incident)\s+reports?\b|\breport\s+(?:a|the|this|that)\s+(?:bug|issue|error|problem)/u;
+const codeDocumentation = /readme|changelog|contributing|api\s?(?:문서|docs?\b|reference)|docstrings?|jsdoc|javadoc|주석|\b(?:agents|claude|gemini|skill|security|code_of_conduct|license|authors|architecture|support|governance)\.md\b|\bdocs\/|\b(?:bug|test|coverage|error|crash|lint|issue|incident)\s+reports?\b|\breport\s+(?:a|the|this|that)\s+(?:bug|issue|error|problem)/u;
 
 // Returns the office skills a bare-lit prompt asks for, slides first when both are named.
 const officeIntent = (normalized) => {
@@ -1140,7 +1142,7 @@ const rulesBlockOrEmpty = (build) => {
   }
 };
 
-const staticRulesContext = ({ cwd, sessionId, maxRuleChars, maxResultChars }) =>
+const staticRulesContext = ({ cwd, sessionId, maxRuleChars, maxResultChars, maxResultBytes }) =>
   rulesBlockOrEmpty(() =>
     staticRulesBlock({
       cwd,
@@ -1148,6 +1150,7 @@ const staticRulesContext = ({ cwd, sessionId, maxRuleChars, maxResultChars }) =>
       sessionId,
       ...(maxRuleChars === undefined ? {} : { maxRuleChars }),
       ...(maxResultChars === undefined ? {} : { maxResultChars }),
+      ...(maxResultBytes === undefined ? {} : { maxResultBytes }),
     }),
   );
 
@@ -1254,11 +1257,12 @@ switch (eventName) {
     // Prompt-time static injection is the straggler lane: SessionStart already recorded
     // what it injected, so this is normally empty and only speaks when a rule file
     // appeared mid-session. Reduced budget, because it can fire on every turn.
-    const promptRulesFor = (maxResultChars = DEFAULT_PROMPT_MAX_RESULT_CHARS) => staticRulesContext({
+    const promptRulesFor = (maxResultChars = DEFAULT_PROMPT_MAX_RESULT_CHARS, maxResultBytes) => staticRulesContext({
       cwd: typeof input.cwd === "string" ? input.cwd : process.cwd(),
       sessionId: input.session_id,
       maxRuleChars: Math.min(DEFAULT_PROMPT_MAX_RULE_CHARS, maxResultChars),
       maxResultChars,
+      maxResultBytes,
     });
     // The exact-bare canonical routes and the trusted-resume authority envelope are
     // deliberately excluded: both are fixed payloads where an appended block would
@@ -1269,9 +1273,11 @@ switch (eventName) {
         ? undefined
         : maxBytes - Buffer.byteLength(context, "utf8") - separatorBytes;
       if (remainingBytes !== undefined && remainingBytes <= 0) return context;
-      const promptRules = promptRulesFor(remainingBytes === undefined
-        ? DEFAULT_PROMPT_MAX_RESULT_CHARS
-        : Math.floor(remainingBytes / 4));
+      // Count the rules in real bytes: a worst-case bytes-per-char guess left a long install
+      // path in the context with too little room for even a rule's first line.
+      const promptRules = remainingBytes === undefined
+        ? promptRulesFor()
+        : promptRulesFor(Math.min(DEFAULT_PROMPT_MAX_RESULT_CHARS, remainingBytes), remainingBytes);
       if (!promptRules) return context;
       const combined = `${context}\n\n${promptRules}`;
       return maxBytes === undefined || Buffer.byteLength(combined, "utf8") <= maxBytes

package/plugins/litclaude/bin/litclaude-hud.js

@@ -2,7 +2,7 @@
 
 import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
   accentCodeForName,
@@ -13,8 +13,8 @@ import {
   rainbowText,
   toneText,
 } from "../lib/hud-accent-palette.mjs";
-import { latestUsageTokens } from "../lib/cache-measurement.mjs";
-import { readIgnitionState, renderIgnitionSegment } from "../lib/hud-ignition.mjs";
+import { latestUsageTokensCached } from "../lib/cache-measurement.mjs";
+import { ignitionStatePath } from "../lib/hud-ignition.mjs";
 import { jevHudState } from "../lib/jev-skill-hint.mjs";
 import { resolveProjectStateRoot } from "../lib/project-state-root.mjs";
 import { recordContextUsage, resolveAutoHandoff } from "../lib/auto-handoff.mjs";
@@ -77,6 +77,19 @@ const shortModel = (raw) => {
   return compact.slice(0, 10) || "?";
 };
 
+// A million-token window reads as 1m, and smaller ones keep their k count.
+const formatWindow = (size) => {
+  if (size >= 1000000 && size % 100000 === 0) return `${size / 1000000}m`;
+  return `${Math.max(1, Math.round(size / 1000))}k`;
+};
+
+// Claude Code sends effort.level only for models that take the effort parameter.
+const EFFORT_LEVELS = new Set(["low", "medium", "high", "xhigh", "max"]);
+const effortLabel = (status) => {
+  const level = status.effort?.level;
+  return EFFORT_LEVELS.has(level) ? `[${level}]` : "";
+};
+
 const clamp = (value, min = 0, max = 100) => Math.max(min, Math.min(max, Number.isFinite(value) ? value : min));
 
 const displayPercent = (value) => Math.round(clamp(value));
@@ -111,7 +124,8 @@ const latestUserMessage = (transcriptPath) => {
   for (let index = lines.length - 1; index >= 0; index -= 1) {
     try {
       const event = JSON.parse(lines[index]);
-      if (event.type !== "user") continue;
+      // Loaded skill bodies and compaction summaries are host-written user entries, not prompts.
+      if (event.type !== "user" || event.isMeta === true || event.isCompactSummary === true) continue;
       const content = event?.message?.content;
       const text = Array.isArray(content)
         ? content.filter((part) => part?.type === "text").map((part) => part.text).join(" ")
@@ -227,9 +241,9 @@ const formatReset = (value) => {
   const minutes = Math.max(0, Math.floor((target - Date.now()) / 60000));
   const hours = Math.floor(minutes / 60);
   const days = Math.floor(hours / 24);
-  if (days > 0) return `↻${days}d${hours % 24}h`;
-  if (hours > 0) return `↻${hours}h${minutes % 60}m`;
-  return `↻${minutes}m`;
+  if (days > 0) return `↻ ${days}d${hours % 24}h`;
+  if (hours > 0) return `↻ ${hours}h${minutes % 60}m`;
+  return `↻ ${minutes}m`;
 };
 
 const coloredText = appearance === "dark";
@@ -239,13 +253,13 @@ const formatUsageSegment = (label, value, reset) => {
   const labelText = text(label);
   if (value === null) {
     return coloredText
-      ? `${labelText} ${accent("[")}${colors.accent}░░${colors.reset}${accent("]")} ${accent("--%")}`
-      : `${labelText} [${makeBlockBar(0, 2)}] --%`;
+      ? `${labelText} ${accent("[")}${colors.accent}░░${colors.reset}${accent("]")}${accent("--%")}`
+      : `${labelText} [${makeBlockBar(0, 2)}]--%`;
   }
   const pct = displayPercent(value);
   const resetText = formatReset(reset);
   const pctText = coloredText ? `${barColor(pct)}${pct}%${colors.reset}` : `${pct}%`;
-  return `${labelText} ${accent("[")}${makeBlockBar(pct, 2)}${accent("]")} ${pctText}${resetText ? ` ${text(resetText)}` : ""}`;
+  return `${labelText} ${accent("[")}${makeBlockBar(pct, 2)}${accent("]")}${pctText}${resetText ? ` ${text(resetText)}` : ""}`;
 };
 
 // Optional Jev skill hint badge, attached to the model label: nothing while LITCLAUDE_JEV is
@@ -312,13 +326,12 @@ const main = async () => {
   const version = readVersion();
   const model = shortModel(status.model?.display_name ?? status.model?.id);
   const maxContext = Number(status.context_window?.context_window_size ?? 200000);
-  const maxK = Math.max(1, Math.round(maxContext / 1000));
-  const tokens = latestUsageTokens(status.transcript_path);
-  const estimatedTokens = tokens > 0 ? tokens : 20000;
+  const windowText = formatWindow(maxContext);
   const statusContextPct = firstNumber(status.context_window?.used_percentage, status.context_window?.usage_percentage);
-  const rawContextPct = statusContextPct === null ? Math.floor((estimatedTokens * 100) / maxContext) : statusContextPct;
-  const contextPct = displayPercent(rawContextPct);
-  const knownContextPct = statusContextPct !== null ? statusContextPct : tokens > 0 ? rawContextPct : null;
+  const usageCachePath = join(dirname(ignitionStatePath(status.session_id)), `usage-${basename(ignitionStatePath(status.session_id))}`);
+  const tokens = statusContextPct === null ? latestUsageTokensCached(status.transcript_path, usageCachePath) : 0;
+  // Without a host percent or a transcript usage record the size is unknown, and the line says so.
+  const knownContextPct = statusContextPct !== null ? statusContextPct : tokens > 0 ? Math.floor((tokens * 100) / maxContext) : null;
   const usage = parseUsage(status);
   const usageText = ` ${accent(sep)} ${formatUsageSegment("5h", usage.fiveHour, usage.fiveHourReset)} ${accent(sep)} ${formatUsageSegment("1w", usage.weekly, usage.weeklyReset)}`;
   const git = gitStatus(status.cwd);
@@ -327,13 +340,14 @@ const main = async () => {
     depth: colorDepth,
     appearance,
   });
-  const contextText = `${text("ctx")} ${accent("[")}${makeContextBar(contextPct)}${accent("]")} ${text(`${contextPct}%/${maxK}k`)}`;
-  const ignition = renderIgnitionSegment(readIgnitionState(status.session_id), {
-    depth: plainOutput ? "plain" : colorDepth,
-  });
+  const contextPct = knownContextPct === null ? null : displayPercent(knownContextPct);
+  const contextText = contextPct === null
+    ? `${text("ctx")} ${text(`?/${windowText}`)}`
+    : `${text("ctx")} ${accent("[")}${makeContextBar(contextPct)}${accent("]")} ${text(`${contextPct}%/${windowText}`)}`;
+  const effort = effortLabel(status);
   const jev = jevBadge(status);
   const autoHandoff = autoHandoffSegment(status, knownContextPct);
-  const line = `${prefix}${ignition ? ` ${ignition}` : ""} ${accent("|")} ${text(model)}${jev ? ` ${jev}` : ""} ${accent(sep)} ${contextText}${autoHandoff ? ` ${accent(sep)} ${autoHandoff}` : ""}${usageText}${git ? ` ${accent(sep)} ${text("git")} ${text(git)}` : ""}`;
+  const line = `${prefix} ${accent("|")} ${text(model)}${effort ? ` ${text(effort)}` : ""}${jev ? ` ${jev}` : ""} ${accent(sep)} ${contextText}${autoHandoff ? ` ${accent(sep)} ${autoHandoff}` : ""}${usageText}${git ? ` ${accent(sep)} ${text("git")} ${text(git)}` : ""}`;
   process.stdout.write(`${line}\n`);
 
   const lastMessage = latestUserMessage(status.transcript_path);
@@ -344,6 +358,6 @@ const main = async () => {
 };
 
 main().catch((error) => {
-  process.stdout.write(`[🔥LITCLAUDE v${readVersion()}] | HUD unavailable: ${error.message}\n`);
+  process.stdout.write(`[🔥LIT v${readVersion()}] | HUD unavailable: ${error.message}\n`);
   process.exit(0);
 });

package/plugins/litclaude/bin/litclaude-mcp.js

@@ -9,7 +9,7 @@ import {
 } from "../lib/wikify-knowledge.mjs";
 
 const protocolVersion = "2024-11-05";
-const serverVersion = "1.0.21";
+const serverVersion = "1.0.23";
 
 const publicSourceReadTool = {
   name: "public_source_read",

package/plugins/litclaude/hooks/hooks.json

@@ -1,4 +1,5 @@
 {
+  "modules": ["./lit-mod.mjs"],
   "hooks": {
     "SessionStart": [
       {

package/plugins/litclaude/hooks/lit-band-client.mjs

@@ -0,0 +1,44 @@
+// The LIT band's surface module: the `Client` element lit-mod.mjs draws above the prompt. It runs on
+// the drawing thread with no mods API, keeps the band's timeline in its local state, and animates on
+// the surface's own frame clock only while something moves; once the timeline settles it stops its
+// timer and the band stays still until the hooks module hands it a new model.
+
+import { composeBand } from "../lib/mod/frame.mjs";
+import { TIMINGS, motionProfile } from "../lib/mod/motion.mjs";
+import { renderBand } from "../lib/mod/render.mjs";
+import { advanceTimeline, createTimeline, sampleTimeline, timelineBusy } from "../lib/mod/timeline.mjs";
+
+// The timeline lives in one holder object that the frame timer and every draw share. The timer
+// never reads `surface.state` back, so a draw that folded in a new model is never overwritten by a
+// tick that started from an older copy.
+export default function LitBand(props, surface) {
+  const profile = motionProfile(props?.motion);
+  const model = props?.model;
+  const empty = () => surface.elements.Box({ children: [] });
+  if (!model) return empty();
+
+  const holder = surface.state?.live ?? { now: 0, model: null, timeline: null, stop: null };
+  if (holder.timeline === null) {
+    holder.timeline = createTimeline(model, 0, profile);
+    holder.model = model;
+  } else if (holder.model !== model) {
+    holder.timeline = advanceTimeline(holder.timeline, model, holder.now, profile);
+    holder.model = model;
+  }
+
+  if (holder.stop === null && timelineBusy(holder.timeline, holder.now, profile)) {
+    holder.stop = surface.every(TIMINGS.frame, () => {
+      holder.now += TIMINGS.frame;
+      if (!timelineBusy(holder.timeline, holder.now, profile)) {
+        holder.stop?.();
+        holder.stop = null;
+      }
+      surface.setState({ live: holder, now: holder.now });
+    });
+  }
+  if (surface.state?.live !== holder) surface.setState({ live: holder, now: holder.now });
+
+  if (!model.visible && !timelineBusy(holder.timeline, holder.now, profile)) return empty();
+  const frame = composeBand(model, sampleTimeline(holder.timeline, holder.now, profile), { columns: props.columns, glyphs: props.glyphs, accent: props.accent });
+  return renderBand(surface.elements, frame);
+}