AI-generated illustrationExtend Claude Code from the Inside: Build a Forkable Visual Mod
Build Model Ledger, a Claude Code mod that draws per-model tokens and estimated cost in the session, test it offline, break it, and decide which mods may load.
- Reading
- 88 min
- Workshop
- 120 min
- Stack
- TS · Claude Code 2.1.325 · Node.js 22 · pnpm 12
- Version
- 1.0.0
- Last verified
- Nov 15, 2026
01Outcomes
What you will build and be able to do
Each outcome has an observable criterion. The lab and the assessment check exactly these, nothing more and nothing less.
OBJ-001
Explain what a mod is and how it loads, then inspect one
Explain what a mod is and how it loads, then inspect one: read its register function, run "claude plugin validate --strict --json", list it in /plugin, load it with claude --plugin-dir, read the build's generated types, and use hot reload.
OBJ-002
Collect per-step usage and keep state
Collect per-step usage and keep state: a turn.step async generator reading result.usage, e.agentId and result.serverToolUses, an agent.spawn hook building the subagent tree, $.session.usage() readings, and totals that survive a module reload, /clear and organization-managed sessions.
OBJ-003
Render across surfaces
Render across surfaces: a Pane with a bounded terminal Raster bar and heat chart, a Box and Text fallback for Desktop and VS Code, an AbovePrompt band, and a /ledger command.
OBJ-004
Diagnose and repair four seeded failures
Diagnose and repair four seeded failures (the 10-second hook limit, a self-opened pane below 144 columns, Raster on Desktop, an oversized Raster), each from the line Claude Code prints, with a regression test that fails before the fix.
OBJ-005
Apply safety and organization controls
Apply safety and organization controls: an opt-in mutating guard with a .catch fallback, cost labeled as an estimate, no secret or network capability in a visual mod, a tier('prepend') policy mod, and managed settings (allowManagedModsOnly on the built-in guard, prependPlugins, disableSideloadFlags, disableAllHooks), written up in trust-boundaries.md.
02Prerequisites and setup
Unpack the download and check your tools ($0.00)
- Node.js 22.18.0 or later and pnpm 12. The labs pin Node.js 22.23.5 (.node-version) and pnpm 12.14.0 through Corepack (corepack enable reads the packageManager field). The lab kit is plain TypeScript that Node runs through its built-in type stripping, so pnpm install installs nothing.pnpm installation guide
- Git, a POSIX shell, and working TypeScript. You write hooks in TypeScript and read type declarations.
- Claude Code 2.1.325 from the native installer. "claude plugin validate" and "claude plugin test" run offline with no sign-in and cost $0.00. Claude Code 2.1.311 (npm stable on 2026-11-14) runs every mechanism here the same way, but its validate skips the TypeScript check, which several labs rely on; 2.1.323 added that check (Claude Code changelog, checked 2026-11-15).Claude Code setup
- For the optional live route only: an Anthropic API key in a workspace with a spend limit you control. Each live task runs in a scratch HOME with --max-budget-usd and --max-turns and costs about $0.02 to $0.05. A terminal at least 144 columns wide shows the pane that opens itself; LAB-003 uses a narrower one on purpose.
- Guide 05 and Guide 10, or equivalent experience with plugins, skills and settings hooks. The first lesson section restates what this guide uses from them. Guide 07 helps, because Model Ledger draws the routing it measures.Read the primer
unzip -q claude-code-visual-mod-labs.zip -d visual-mod-workcd visual-mod-work/labscorepack enablenode --versionpnpm --versionclaude --version03The system picture
Model Ledger: one wiring file, two seams

Extended description
hooks/register.ts registers 9 hooks on 8 events (classic.SessionStart, session.start, turn.start, turn.step, agent.spawn, turn.complete, command.run and ui.render, which has one hook for the pane and one for the band above the prompt). It is the only file that calls the mods API, and it writes each call out in full so "claude plugin validate" lists it. It passes plain inputs to the modules in src/, which never see $: collector.ts (seam 1) turns events into records, ledger-store.ts holds the reducers and store keys, pricing.ts the dated price table, spawn-guard.ts the reroute decision, and render.ts (seam 2) builds the tree from a ledger and a size.
With their results, register.ts writes the live ledger to $.state atoms, which /clear resets, and saves it with $.store.set to the store, which holds up to 4 MiB and is kept across sessions. Writing an atom makes Claude Code redraw the pane and the band: the terminal draws the tree's Raster bars, and Desktop and VS Code draw Box and Text. A fork edits the modules in src/ and registers its own hooks in the wiring file.
04Lesson
What this guide takes from Guides 05 and 10
Three Claude Code extensions get confused, and the differences decide which one a job needs:
| Aspect | Settings hook (Guide 05) | Skill (Guide 10) | Mod (this guide) |
|---|---|---|---|
| What it is | A command in settings.json that Claude Code runs on events such as PreToolUse | Instructions and files Claude loads when a task matches | A plugin whose TypeScript or JavaScript code registers hooks inside Claude Code |
| Where it runs | A separate process per event | In Claude's context | In Claude Code's hooks runtime, with the $ mods API |
| Can it draw in the interface | No | No | Yes: panes, a band above the prompt, transcript lines |
| Can it keep state | Only in files its command writes | Only in files its scripts write | $.state in memory and $.store on disk |
| Can it change what Claude Code does | Allow, deny or add feedback around tool calls | Shape Claude's work | Rewrite or answer events, such as a subagent's model |
A plugin is a directory with .claude-plugin/plugin.json. Guide 10's skills and this guide's mod both ship that way, and claude plugin validate checks both. The neighbors keep their subjects: Guide 05 owns headless verification, settings hooks, deny rules and OS sandboxing; Guide 10 owns SKILL.md packaging and activation testing; Guide 07 owns measuring whether routing saves money; Guide 03 owns prompt injection and containment.
What a mod is and how it loads
"A mod is a plugin whose code registers event handlers, called hooks" (Mods overview, checked 2026-11-15). Model Ledger's hooks/hooks.json names one hooks module:
{ "modules": ["./register.ts"]}hooks/register.ts exports register(on, options). Claude Code calls it once when the module loads; on registers hooks, and options holds "the values of the userConfig fields the manifest declares, with defaults filled in" (Mods reference, checked 2026-11-15). There is no build step: Claude Code runs .ts and .js directly.
How a mod reaches a session:
- Installed through
/plugin, or loaded for one session withclaude --plugin-dir ./model-ledger. "Claude Code watches a directory loaded with--plugin-dirand hot-reloads the hooks module when a file in it changes" (Create a mod), and each reload runsregisterandsession.startagain. "Mods are on by default. In the terminal, use Claude Code v2.1.287 or later" (Mods overview)./pluginshows a count line such as1 mod active · model-ledger. - Print mode and the Agent SDK run hooks too, the overview says, unless you pass
--bareor--safe-mode; this guide ran print mode, not the SDK. In the spike,--bareprintedhooks module spike-probe@inline not loaded: installed plugins that are not managed load no hooks module in this mode (--bare); built-in plugins load regardless. - Generated types. When Claude Code loads a mod from
--plugin-dirin an interactive session, it writes declaration files into the mod's.claude-plugin/types/. "The events and methods can change between releases, so trust these files over any page, this one included, when they disagree" (Create a mod, checked2026-11-15). The interactive session also writes atsconfig.jsonat the top of the mod folder; the labs'.gitignorelists both.
The middleware chain
Every hook sits in a chain. It receives $ (the mods API), e (the event) and next (the rest of the chain, ending in Claude Code's own behavior), and it does one of three things: observe (return next(e), or await it and read the result), rewrite (return next({ ...e, model })), or answer without calling next. "The event itself is immutable: it's deeply frozen, and assigning to a field throws" (React to events, checked 2026-11-15), which is failure gallery card F-06.
The failure rule matters more than any other: "If the handler itself throws or times out, Claude Code skips the hook as if it had no handler" (React to events). A hook that guards something fails open unless you add a .catch handler, which answers in its place.
One more rule applies when a module registers two hooks on one event, as a gate and a recorder for Bash would. Claude Code runs a module's hooks for an event as one unit. In this guide's probes, when the second of two tool.call hooks threw, the first hook's .catch answered, with next.called false, and its next(e) ran the tool, so the second hook's own .catch, which would have refused, never ran. That held live on 2.1.325 and in the test kit on 2.1.325 and 2.1.311. Register a hook that guards something ahead of the other hooks on its event, so its .catch is the one that answers.
What validate reads
claude plugin validate --strict --json <dir> analyzes the manifest and hooks module without running them and lists what the module hooks and calls. For the finished mod it prints notes such as:
Offline output, recorded 2026-11-15 with Claude Code 2.1.325 ($0.00):
"./register.ts hooks: session.start, classic.SessionStart{source=clear|resume|fork}, turn.start, turn.step, agent.spawn, turn.complete, command.run{command=ledger}, ui.render{component=Pane} (default matcher key: plugin), ui.render{component=AbovePrompt} (default matcher key: plugin)","./register.ts answers its own command: command.run{command=ledger}","./register.ts gating hook with .catch: classic.SessionStart{source=clear|resume|fork}","./register.ts gating hook with .catch: agent.spawn","./register.ts calls: $.clock.now, $.command.register, $.session.id, $.session.usage (via engineUsd, reconcile), $.state.get, $.state.set, $.store.delete (via startFresh), $.store.get (via addToHistory, loadToday, restoreAfterReset, restoreOrStart), $.store.keys (via startFresh), $.store.set (via addToHistory, save), $.ui.close, $.ui.log, $.ui.open (via openPane), $.ui.resolve","./register.ts state writes: model-ledger.guard, model-ledger.ledger, model-ledger.notice, model-ledger.today","./register.ts state reads: model-ledger.guard, model-ledger.ledger, model-ledger.notice, model-ledger.today"Those lists are only exact if you write every call in full. "Don't assign $ or one of its namespaces to a variable, destructure it, or index it with a computed name" (Create a mod). On 2.1.325, --strict also type-checks the module and its tests against the build's own declarations, and fails on any finding.
The JSON has two more sections. directory holds the plugin directory's listing checks, such as a missing icon; they do not count toward success, and the section's own note says passing here does not mean the directory accepts the plugin when it has a hooks module. advice suggests an install line for the README. Both are about publishing a listing, which the local labs do not need.
Model Ledger's shape: one wiring file, two seams
| File | Job | Sees $ |
|---|---|---|
hooks/register.ts | Wires each event to the pure modules and writes every mods API call in full | Yes |
src/collector.ts (seam 1) | Turns a turn.step result, an agent.spawn and a usage reading into plain records | No |
src/ledger-store.ts | Pure reducers (applyStep, applySpawn, applyUsage) and the store keys | No |
src/pricing.ts | The dated price table and its userConfig override | No |
src/render.ts (seam 2) | Draws the pane, band and /ledger text from a ledger and a size | No: it receives the element constructors |
src/spawn-guard.ts | Decides whether a spawn is rerouted | No |
types/index.d.ts | Declares the state atoms and record types | No: declarations only |
Keeping $ out of src/ buys three things. The pure modules run under plain Node, so the offline replays draw from them and the unit tests need no stubs. Validate's lists stay complete, because every call is in one file. And a fork changes what is collected and drawn in the pure modules, touching the wiring only to register its own hooks.
The mod also calls nothing a visual mod does not need: no $.fs, $.process, $.http, $.env, $.mcp or $.model. The lab kit's contract checker reads validate's call list and fails a copy that adds one (rule MLC-08), so a fork that quietly uploads usage fails before anyone loads it.
Collecting usage: turn.step, agent.spawn and the engine's figure
agent.spawn and one turn.step through the stages, plays the run's other four steps, and ends on this frame. Silent loop, 18 seconds.Extended description
The session is a print-mode run of the delegated lookup task with the guard on, recorded on 2026-11-15 and played back through Model Ledger's own modules, as pnpm mod:replay does. At 2.39 s, agent.spawn fires for an Explore subagent whose parent runs on claude-sonnet-5-5. The guard asks for claude-haiku-5-5 with next({ ...e, model }), $.state.set adds a subagent row, $.store.set saves the ledger, and the pane, with no step yet, reads No model steps yet. Send a prompt to fill the ledger.
At 2.41 s, the first turn.step result arrives from the main loop on claude-sonnet-5-5: 2 input, 189 output, 11,495 cache-read and 5,470 cache-write tokens. The handler's const result = yield* next(e) hands the result on, $.state.set records 1 step and $0.0167 estimated, and the pane draws a sonnet bar. The subagent's three steps on claude-haiku-5-5 follow at 4.63 s (2 input, 307 output, 0 cache-read and 8,955 cache-write tokens; $0.0180 in all), 5.81 s (2, 111, 8,955 and 690; $0.0182) and 6.83 s (2, 55, 9,645 and 237; $0.0184).
The main loop's last step at 7.89 s (2, 43, 16,965 and 446) brings the ledger to 5 steps and $0.0216 estimated, and the pane shows a full sonnet bar beside a short haiku bar.
Every step, from an async generator
"Write a turn.step hook as an async generator, because the event streams. yield* next(e) forwards the response as it streams and evaluates to the finished result" (React to events). Model Ledger's hook passes every chunk through unread and records the result:
// turn.step must be an async generator: yield* passes every chunk through, and the// result, with its usage, arrives when the step endson('turn.step', async function* ($, e, next) { const result = yield* next(e) const rec = stepRecord(e, result, await $.clock.now()) await ensureLedger($) if (rec === null) { const at = await $.clock.now() await update($, ledger, (l) => (l === null ? l : applyNoUsage(l, at))) } else { await update($, ledger, (l) => (l === null ? l : applyStep(l, rec, prices))) await addToHistory($, rec, stepUsd(rec, prices)) } await save($) return result})result.usage carries input_tokens, output_tokens, cache_read_input_tokens, cache_creation_input_tokens and model; e.agentId is set on a subagent's steps. The pricing module turns those four counts into dollars at the dated list rates, with cache writes at the 5-minute rate, and the ledger keeps per-model rows.
Advisor calls carry no tokens
result.serverToolUses lists tool calls the API ran inside the request, such as the advisor; "Claude Code doesn't run these calls, so no tool.call or tool.check hook fires for them" (React to events). Each entry has a name and timing and no tokens, and result.usage is the executor's alone: "Top-level usage fields reflect executor tokens only" (Advisor tool, checked 2026-11-15). In the spike's advisor run, the steps summed to 285 output tokens while Claude Code's modelUsage reported 919, and the session cost of $0.0747244 included the advisor's sub-inference. So the ledger counts advisor calls and their wall time, and never invents their tokens.
The subagent tree
agent.spawn fires when Claude starts a subagent. The hook records the type, description, requested and parent model, and the agentId it gets back from next, which links the subagent's later steps to its row. It never reads e.prompt, which can hold anything the parent pasted into the delegation (rule MLC-09).
Reconciling with Claude Code's own figure
After each main-loop turn.complete, the mod reads $.session.usage(), which "returns context window use and plan limits" (Use the mods API, checked 2026-11-15), plus Claude Code's cost for the session. The difference between that cost and the priced steps is the row "Not in any step". In print mode it was zero in every ledger run. In interactive sessions it was not, because Claude Code makes requests no step reports: a session title on Haiku 5.5 with the first prompt, and a prompt suggestion after each turn. In the recorded 150-column session, the pane read Not in any step: $0.0068 when the last turn ended. The last suggestion landed after that reading, so /ledger status reads usage again before it answers; its $0.0102 then equaled /cost's $0.0430 less the priced steps.
Both figures are estimates. "Claude Code computes the dollar figure locally from token counts at list price, unless a modelPricing table is in effect" (Manage costs effectively, checked 2026-11-15), and the ledger labels every dollar figure the same way, with the date of its table.
What the measured runs showed
On 2026-11-15, ten measured print-mode runs worked three small tasks (read and answer, a one-line edit checked by tests, and a delegated Explore lookup) with no mod, with a recorder mod alone, and with Model Ledger:
- No overhead. The read-and-answer task cost
$0.017813in all four of its runs, with identicalmodelUsage, and the first request's prompt was16,957tokens with and without Model Ledger. The mod's hooks send nothing to the model; only/ledgeranswers enter the conversation, which is why they are one short line. - Exact per-model figures. In all nine print-mode task runs that loaded Model Ledger (six of the measured runs and three through the lab kit's
kit/live/run.sh), its per-model tokens and dollars equaled Claude Code'smodelUsageandtotal_cost_usd. - The guard moved the subagent. With the guard on,
Exploreran onclaude-haiku-5-5both when the guard asked for the full id and when it asked for the aliashaiku.

claude-sonnet-5-5 at effort medium.Extended description
T1 reads a file and answers, T2 makes a one-line edit that the tests check, and T3 delegates a lookup to an Explore subagent. Each bar is the run's total_cost_usd, split by its modelUsage, and in all nine print-mode runs the ledger's tokens and dollars per model equaled those figures. T1 cost $0.017813 in both measured runs and T2 $0.026386.
With the guard off, T3 ran entirely on claude-sonnet-5-5 for $0.038437. With the guard on, the subagent ran on claude-haiku-5-5: $0.021622 in all, $0.019964 of it on Sonnet and $0.001658 on Haiku, and $0.025403 when the guard asked for the alias haiku ($0.023883 and $0.001521). The kit rows are three runs through the lab kit's kit/live/run.sh, which leaves the guard off: T1 for $0.017835, T3 for $0.049309 with its subagent on Sonnet, and T1 again for $0.017866.
The panel is an interactive session at 150 columns that ran T1 and then T3 with the guard on: /cost read $0.0430, Model Ledger priced its steps at $0.0328 ($0.0313 on Sonnet, $0.0015 on Haiku), and $0.0102 was in no step. That remainder is requests Claude Code makes on its own, which no step reports; the debug log of an earlier capture of the same steps named a session-title request and prompt suggestions. These are single runs of small tasks: they show that the ledger matches Claude Code's figure, not what a routing choice saves.
These are single runs of small tasks. They show that the ledger reports what Claude Code reports; whether a routing choice saves money on your work is Guide 07's method.
State that outlives a reload and a /clear
Model Ledger keeps two kinds of state:
$.stateatoms hold the live ledger. "It's reactive state: aui.renderhook that reads a value subscribes to it, so Claude Code redraws that site each time you write the value" (Draw in the interface, checked2026-11-15). Atoms survive a module reload./clear,/resumeand/branch"reset every$.statevalue to its default, andsession.startdoesn't fire again" (Draw in the interface).$.storeis "a JSON key-value store of your plugin's own, kept between sessions" (Use the mods API), up to 4 MiB in total, and "every session on your machine that runs your mod shares one$.store. Agetfollowed by asetisn't atomic" (Draw in the interface). So each session writes under its own key (ledger:v1:<session id>), the newest ten are kept, and the shared daily history is read again right before each write.
After /clear, a classic.SessionStart hook with source clear, resume or fork restores the saved ledger. That hook is not enough on its own. Where an organization manages Claude Code, the built-in guard passes over a user mod's classic.* hooks; the spike's /plugin Errors tab said Its hooks on classic.SessionStart do not run here: where an organization manages Claude Code, these events pass over the plugins you install. So every writer first calls ensureLedger, which restores the saved copy whenever the atom is empty:
// Runs after /clear, /resume and /branch (source 'fork'), which reset every $.state valueon('classic.SessionStart', { source: ['clear', 'resume', 'fork'] }, async ($, e, next) => { await restoreAfterReset($) // Before this process's first session.start, the session is not bound yet if (!started) rebaseAtStart = true return next(e)}).catch(async ($, e, next) => { // A failed restore must not hold up the session: it goes on, and the next turn restores $.ui.log('restoring the totals failed (' + next.error.kind + '); the next turn tries again') return next(e)})A module variable keeps the ledger's store key across /clear, where $.state resets, and the atom keeps it across a reload, where module variables reset, so either path finds the right copy.
Recorded behavior worth knowing before you teach it: after /clear, Claude Code's /cost starts again at $0.0000, while Model Ledger restores its totals and shows Context unknown of 1.00M tokens until the next turn reports context. The ledger outlives the conversation that /cost counts.
A resumed claude -p process orders the two start events the other way. classic.SessionStart with source resume runs first, while no session is bound, and $.session.usage() answers a cost of 0 there; by session.start it answers the resumed session's whole cost. The ledger counts every rise in that figure as new spend, so a ledger restored in the first hook counted the resumed cost a second time: in the clean-room walk, /ledger status after a $0.0178 run answered $0.0178 not in any step. Model Ledger now takes the baseline again at session.start for a ledger restored before it, and an Increment 2 test fires the two events in that order.
Drawing on three surfaces

Extended description
The session ran T1 and then T3 with the guard on. Its screen was played back from the session's recorded terminal output with xterm.js and cropped to the pane without scaling. The blue bar is claude-sonnet-5-5: 5 steps, 107.8k tokens, $0.0313.
The short green bar is claude-haiku-5-5, where the guard sent the Explore subagent: 3 steps, 25.8k tokens, $0.0015. The strip of recent steps has one cell per step, colored by cost: the first, the costliest, is red and the other seven are blue. Below it: 133.7k tokens and $0.0328 estimated over 8 steps, context at 22.4k of 1.00M tokens (2 percent), today's total, the guard's state, and the subagent tree, whose row is cut to the pane's width.
The amber line reads $0.0068 because this capture was taken as the last turn ended, before Claude Code's last prompt suggestion landed. /ledger status reads usage again before it answers, and a moment later it answered $0.0102, which is /cost's $0.0430 less the priced $0.0328. Every dollar figure is an estimate at list prices.
The pane and its width
$.ui.open({ id, title }) asks for a pane. One the person asks for opens at any width. One a mod opens on its own, such as at session start, "appears only in a terminal at least 144 columns wide. After the user has opened that pane once themselves, 110 columns is enough" (Draw in the interface). $.ui.open resolves { isPlaced: false, reason } when it waits, and Model Ledger says so in the transcript and the band rather than failing silently. The recorded sessions showed three placements:
| Terminal | The pane opened at start | After /ledger open |
|---|---|---|
| 150 columns | Docks on the right with a 66-column body | Already open |
| 120 columns | Waits, and the mod prints the pane is not shown yet: unasked below 144 columns (120 now): ... | Docks with a 49-column body |
| 80 columns | Waits | Placed inline under the conversation, with a 76-column body |

Extended description
Each picture is a whole terminal screen after the first task, reduced so the pane's position reads at a glance; its text is too small to read by design, and the lines that matter are set beside it. In the 120-column session, Model Ledger asked for its pane at session start, Claude Code held it, and the mod printed model-ledger: the pane is not shown yet: unasked below 144 columns (120 now): placed when the person opens it, or when the terminal is widened to 144 columns. After /ledger open, the pane docked on the right with a 49-column body.
In the 80-column session the notice read (80 now), and /ledger open placed the pane inline under the conversation with a 76-column body. A pane the person opens appears at any width.
focus, closeOnEscape and holdToasts "accept only true. To leave one off, omit it. Passing false throws an error such as ui.open: focus is true or left out" (Draw in the interface), which is card F-08.
Raster on the terminal, text everywhere else
The ui.render hook branches on e.surface, because "apps other than the terminal have no Raster, so check e.surface and draw text there" (Draw in the interface):
on('ui.render', { component: 'Pane' }, async ($, e, next) => { if (e.requestId !== PANE_ID) return next(e) const live = await read($, ledger) const side = await sideNow($, prices, config) const view = { columns: e.props.bodyColumns, rows: e.props.scroll.bodyRows, theme } // Raster is in the terminal's element table only; Desktop and VS Code get the text layout if (e.surface === 'terminal') { const { Box, Text, Raster } = $.ui.resolve(e) return terminalPane({ Box, Text, Raster }, live, side, view) } const { Box, Text } = $.ui.resolve(e) return textPane({ Box, Text }, live, side, view)})A Raster takes "key, columns up to 512, rows up to 256, cells" (Mods reference), and one tree holds at most 262,144 Raster cells. "Each cell is three numbers: the character's code point, its color, and its background color", and "the value 0x01000000, one above that range, means the terminal's default" (Draw in the interface). The renderer fits each Raster to the pane's bodyColumns and to those limits, folds a long session's steps into the heat strip's buckets, and packs cells with its own base64 encoder, since the generated tsconfig.json targets a library without Uint8Array.prototype.toBase64. Where a bar would not fit, it draws the text table instead. Desktop and VS Code always get the table.
Extended description
The bars and tables are the renderer's own output for each surface and width, from the guard-on run of the delegated lookup task recorded on 2026-11-15. On the terminal, the pane's Raster bars are 24 cells wide in the 66-column body of a docked pane at 150 columns and 14 cells wide in the 49-column body at 120 columns, in the renderer's own colors. Desktop and VS Code have no Raster, so they get a Box and Text table of block characters.
At 2.39 s, agent.spawn starts the Explore subagent and every view reads No model steps yet. Send a prompt to fill the ledger. At 2.41 s, a main-loop step on sonnet-5-5 adds $0.0167; the table reads 1 step and 17.2k tokens, with the line Total 17.2k tokens, $0.0167 estimated, 1 step. The subagent's steps on haiku-5-5 add $0.0013 at 4.63 s (1 step, 9.3k tokens), $0.0002 at 5.81 s (2 steps, 19.0k, $0.0015) and $0.0002 at 6.83 s (3 steps, 29.0k, $0.0017).
The last step at 7.89 s adds $0.0032 on sonnet-5-5, for 2 steps, 34.6k tokens and $0.0200. Each step also adds a cell to the strip of recent steps: the first, the costliest, is red and the rest are blue.
The band above the prompt
The AbovePrompt hook draws one dim line and keeps what next(e) returns beneath it, so another mod's band still shows. From 2.1.323, each mod's rows stack; before that, mods shared one band drawing. At narrow widths the band drops its model counts and context first.
One thing only a real terminal shows: the test kit's find returns each Text's children, not laid-out lines, so text cut at a narrow width looks whole in a test. The 49-column dock cut sentences in an early capture, which is why the pane now wraps sentences and cuts only table cells.

borderStyle: 'rounded' draws no border, and Claude Code 2.1.325 says so in the conversation.Extended description
A probe mod drew one pane with three Box elements, each with a different borderStyle, in an interactive session on 2026-11-15. No prompt was sent, so no model request ran, and /cost read $0.0000: everything shown is Claude Code drawing a mod's tree. The screen was played back from the session's recorded terminal output with xterm.js and cropped to the pane without scaling.
'round' draws rounded corners and 'single' square ones; 'rounded', which is not a style, draws the text with no border. Claude Code printed the message below the crop in the conversation and logged it as a warning, while claude plugin validate --strict and the test suite pass the mistake, because neither checks a drawn border.
The /ledger command and the opt-in spawn guard
$.command.register adds /ledger at session start, and an on('command.run', { command: 'ledger' }, ...) hook answers it: status, open, close, reset, export, guard on and guard off. Two details came from the runs. Registering a name that is taken throws, and a hook that throws is skipped, so the mod registers last, inside try, and says when /ledger is unavailable. And a command's text goes into Claude's next request, so status answers in one line. export writes its JSON through $.ui.log, which shows in the transcript and is not sent to the model.
The guard is the one part of Model Ledger that changes what Claude Code does, so it is off by default (guard_enabled: false in userConfig) and /ledger guard on turns it on for one session. "To send a request to a different model, pass next the event with model changed" (React to events):
// The one hook that can change what Claude Code does: off unless the person turns it onon('agent.spawn', async ($, e, next) => { const decision = decideSpawn(guardIsOn(config, await read($, guard)), config, e) const result = decision.action === 'reroute' ? await next({ ...e, model: decision.model }) : await next(e) if (decision.action === 'reroute') $.ui.log(decision.why + ' (guard on; /ledger guard off stops it)') const rec = spawnRecord(e, result, decision.action === 'reroute' ? decision.model : null, await $.clock.now()) if (rec !== null) { await ensureLedger($) await update($, ledger, (l) => (l === null ? l : applySpawn(l, rec))) await save($) } return result}).catch(async ($, e, next) => { // Fail safe for a cost guard: before next, the spawn goes on unchanged; after next, // next(e) hands back what the first call answered without spawning again $.ui.log('the spawn guard failed (' + next.error.kind + '), so the subagent runs as Claude asked') return next(e)})It reroutes only a listed subagent type whose Agent call names no model, never a fork, a resumed agent, a teammate or a workflow agent, and it logs every reroute. Its .catch handler shows what failing safe means for a cost guard: the subagent runs as Claude asked. Failing safe for a policy check means the opposite, refusing the mod, which is LAB-003's org-guard.
Two recorded details to expect. With the full id claude-haiku-5-5, the debug log on 2.1.325 gets an [ERROR] line, ZodError: ... expected one of "sonnet"|"opus"|"haiku"|"fable" (path model), yet the Agent call ends outcome=ok and the subagent runs on Haiku 5.5; with the alias haiku, nothing is logged. The ledger keeps the full id because its price table and rows key on full ids. And whether Explore ran in the background was the parent's choice per call: with the guard on, one run spawned it in the background and one did not, so the guard is not credited with any difference in steps.
Testing a mod offline
claude plugin test [directory] runs *.test.ts files against a stubbed Claude Code, with no network and no sign-in, and "exits with status 1 when a test fails, so it works in CI" (Test a mod, checked 2026-11-15). The rules that trip people, each with a gallery card:
- "Register every stub before the test's first call on
$" (Test a mod). The first call loads the plugins (F-11). - "
session.startdoesn't run by itself" (Test a mod): fire it withawait $.session.start(...). - A stub for a mods API call answers
{ value: ... }or{ deny: 'the reason' }; a stub for an event answers the event's own result (F-12). - "A stub for
turn.stepis an async generator, and the test reads the stream to its end to get the result" (Test a mod). - "For
$.clockcalls, usemock.clock(on), or your mod's$.clock.now()fails withno implementation for clock.now" (Test a mod). $.ui.mount({ ...target, surface })mounts aPaneorAbovePromptonterminal,desktoporvscode, withfind,press,input,selectandunmount.tier('prepend')at the top of a file loads your mod ahead of the others, for policy mods.
Model Ledger's suite has 63 tests in six files: the pure modules, one file per build increment, and one file of regression tests, one per seeded failure. It passes on 2.1.325 and 2.1.311. A surface matrix mounted the pane and the band on all three surfaces at three widths each, fed from four recorded sessions (72 mounts), with the same text and Raster sizes on both versions.
The lab kit adds a contract checker, pnpm mod:check (rules MLC-01 to MLC-12), each rule tagged with the increment from which it must hold, so a checkpoint passes what is done and lists what is still ahead. A checker that never fails proves nothing, so pnpm mod:faults plants one fault per rule and confirms each is caught (12 of 12).
On 2.1.325, validate --strict catches several mistakes before any test runs, because it type-checks the module and the tests. On 2.1.311 the same mistakes show only at runtime, which the gallery cards mark.
Organization controls and trust boundaries
"A mod is code that runs with your permissions, inside Claude Code" (Mods overview). The overview's list of what one can do starts with "Act on your machine as you: read and write files anywhere your user account can, start programs, and make network requests", and it adds: "Mods aren't sandboxed. If you turn on sandboxing, the sandbox isolates the Bash commands Claude runs, and a process that a mod starts runs outside it." Treat a mod like installed native code.
Permission rules do not cover a mod either. With a Read(.env) deny rule in place, a recorded session refused Claude's Read tool (File is in a directory that is denied by your permission settings.) while a small probe mod read the same file with $.fs.read (gallery-probe: gprobe env: $.fs.read(".env") returned 80 characters; first key NORTHSTAR_DEMO_FLAG), as the admin page warns: "With Read(.env) denied, a mod can still read that file with $.fs.read or start a program that does" (Manage mods for your organization, checked 2026-11-15).
The controls live in managed settings, which a person cannot override (/etc/claude-code/managed-settings.json on Linux and WSL, /Library/Application Support/ClaudeCode/managed-settings.json on macOS, per Managed settings, checked 2026-11-15). Each line below was recorded on 2.1.325 against a scratch managed-settings directory, never a real machine's:
| Control | What it does | Recorded line |
|---|---|---|
The built-in guard, sec-default@builtin (cc-plugin-sec-default in /plugin) | Runs ahead of user mods once any managed setting exists; a file holding only {} does not seat it | cc-plugin-sec-default@builtin seated outermost: this machine has managed settings |
allowManagedModsOnly, an option on the guard under pluginConfigs["cc-plugin-sec-default@builtin"] | Only the organization's mods load | refused by cc-plugin-sec-default: mods are limited to your organization's by policy (allowManagedModsOnly) |
disableSideloadFlags | "rejects --plugin-dir and --plugin-url at startup, and keeps mods Claude writes during a session from loading" (admin page) | --plugin-dir is disabled by your organization's managed settings (disableSideloadFlags), exit 1 |
disableAllHooks | No hook or mod from an installed plugin runs; built-in mods still do | not loaded: disableAllHooks in managed settings |
prependPlugins with a policy mod | The policy mod's plugin.register hook reads each user mod's calls before it loads and can refuse it. "With prependPlugins, also list sec-default@builtin to keep the built-in guard" (admin page) | refused by org-guard: Northstar policy: mods may not call http.fetch |
LAB-003's org-guard is that policy mod. It reads e.uses.calls, "the mods API methods the mod calls, each written namespace.method such as process.run" (admin page), and refuses a user mod that starts processes, uses the network or writes files:
// Northstar Parcel's policy mod. An administrator lists it first in prependPlugins, so it// sees every user's mod before that mod loads. It reads the calls the mod's code makes,// the list `claude plugin validate` prints, and refuses a mod that reaches past what a// visual mod needs: starting processes, the network, or writing files.import type { On } from 'claude-code' /** The mods API methods no user's mod may call, spelled as e.uses.calls lists them. */const BLOCKED_CALLS = ['process.run', 'process.spawn', 'http.fetch', 'fs.write'] export function register(on: On) { on('plugin.register', async ($, e, next) => { const blocked = e.uses.calls.filter((call) => BLOCKED_CALLS.includes(call)) // Every mod a person installs or loads with --plugin-dir is tier 'user'; the // organization's own mods and the built-in ones pass if (e.tier === 'user' && blocked.length > 0) return { refuse: 'Northstar policy: mods may not call ' + blocked.join(', ') } return next(e) }).catch(async ($, e, next) => { // A check that throws or runs past its time limit would otherwise let the mod load if (e.tier !== 'user') return next(e) return { refuse: 'Northstar policy check failed, so this mod was not loaded' } })}The .catch handler is not decoration: "If your plugin.register hook throws or exceeds its time limit, Claude Code skips the hook, so the check fails open and the mod it was checking loads" (admin page). Card F-13 shows both outcomes.
Two consequences to tell your users. When policy keeps a mod from loading, its slash command is no longer a command, so Claude Code sends what was typed to the model as a prompt: under allowManagedModsOnly, /ledger status became a model turn costing $0.0188 whose answer said the command is not installed. And "none of these controls sandboxes a mod. A mod you allow runs as the user, with the user's access to files, processes, and the network" (admin page). Model Ledger's trust-boundaries.md states what it receives, the one thing it changes, where its data goes, what it does not promise and what an administrator controls.
Forking the template
The point of the two seams is that the next team does not start over. FORKING.md in the mod walks a fork step by step; the short version:
- Copy the folder and rename the plugin, its options and its store key prefix, so the two mods never read each other's data.
- In
src/collector.ts, write a record for the new stream from the hook's input and result, free of$. - In
src/ledger-store.ts, replace per-model rows with rows for the new stream. - In
src/render.ts, keep the layout functions (fitRaster,packCells, the text table) and change what the bars measure. - In
hooks/register.ts, register the new hooks with every$call written in full, and keep any hook that changes behavior opt-in with a.catchhandler. - Copy the test pattern, then run
pnpm mod:check <fork> --fork. Nine rules hold for any visual mod: strict validate with its type check,turn.stepas anasync function*wherever you register it, a.catchon every gating hook,$written in full withsrc/kept pure,Rasteronly behind the terminal branch, the allowlist, no reads of a subagent's prompt, and tests that pass and mount all three surfaces. The three rules that run Model Ledger's own renderer, guard and price table are skipped, so your tests carry those properties for the new stream: limits at every width, any hook that changes behavior off by default, and an estimate label on any dollar figure. The check is a self-check, not a grade.
The assessment is exactly this: a fork that charts test runs from a data source you have not seen.
Troubleshooting
T-01: pnpm is not found or is the wrong major version
Run corepack enable with Node.js 22.18.0 or newer on your PATH, so Corepack reads "packageManager": "pnpm@12.14.0". Check with node --version and pnpm --version. Every script in package.json is also a plain node command you can run directly.
T-02: The kit says Claude Code is not found
The kit calls claude on your PATH. Set CLAUDE_BIN to the binary's full path if it lives elsewhere, and check claude --version.
T-03: MLC-01 passes on 2.1.311, which skips the TypeScript check
That version runs mods, but its validate does not type-check them, so F-03, F-06, F-08 and F-12 show no static error there. Install 2.1.325 for the labs. Its validate notes also leave out (default matcher key: plugin) after the two ui.render hooks, which register and draw the same way on both versions.
T-04: validate --strict fails on an import ending in .ts
On 2.1.325 the type check refuses .ts import specifiers (TS5097), although Claude Code runs them. Import ./name.js, as every module in the lab does; the kit resolves those to the .ts files under plain Node.
T-05: The pane does not open at session start
A pane the mod opens on its own waits for 144 columns. Widen the terminal or run /ledger open; the transcript line and the band say when it is waiting.
T-06: /ledger reached the model as a prompt
The mod did not load: policy refused it, --bare or --safe-mode skipped it, or the module failed validation. Run /plugin and read the Errors tab, or run claude plugin validate --strict on the folder.
T-07: Hot reload printed nothing, or reload failed
Reload works in interactive sessions started with --plugin-dir. Save inside the folder you passed and look for the reloaded (N hooks: ...) line. reload failed, the previous version stays loaded: <reason> means your last working version is still running and the reason names what to fix (Troubleshoot a mod, checked 2026-11-15); /reload-plugins reloads every plugin by hand.
T-08: A live run stops with error_max_budget_usd
--max-budget-usd is checked after each model turn, so the turn that crosses the cap finishes first. Raise the cap a little for the task, and keep a total cap across loops; kit/live/run.sh sets both.
Lines that look like failures and are not
[ERROR] ... ZodError ... expected one of "sonnet"|"opus"|"haiku"|"fable"in the debug log when the guard asks for the full idclaude-haiku-5-5: the subagent still runs on Haiku 5.5 (The/ledgercommand and the opt-in spawn guard).Not in any step: $...in the pane: Claude Code's own requests, which no step reports (Collecting usage:turn.step,agent.spawnand the engine's figure).Context unknown of 1.00M tokensafter/clear: no turn has reported context yet (State that outlives a reload and a/clear).ICON_MISSINGand an install-line suggestion in validate'sdirectoryandadvicesections: listing readiness, not a failure (What a mod is and how it loads).
What this guide leaves out
- Headless verification, settings hooks, deny rules and OS sandboxing belong to Guide 05.
- Packaging skills, progressive disclosure and activation testing belong to Guide 10.
- Measuring whether a routing choice saves money belongs to Guide 07. Model Ledger draws routing; it does not prove a saving.
- Prompt injection and containment belong to Guide 03.
- Publishing a mod to a marketplace or the plugin directory, mods that call
$.model,Svgdrawings, and custom tools are outside one visual mod. - The Desktop app and VS Code windows were not run for this guide. Their behavior is taught from the documentation and checked through test-kit mounts with
surface: 'desktop'and'vscode'.
Quick reference
Commands
pnpm mod:check [folder] [--upto start|inc1|inc2|inc3|inc4] # contract rules MLC-01 to MLC-12 ($0.00)pnpm mod:check <fork> --fork # the nine rules any visual mod keeps ($0.00)pnpm mod:test [folder] [--upto start|inc1|inc2|inc3|inc4] # claude plugin test, by increment ($0.00)pnpm mod:replay trace replays/t3-explore-guard-on.jsonl # draw a recorded session offline ($0.00)pnpm mod:seed <sf-1|sf-2|sf-3|sf-4|all> # seeded failures F-01 to F-04 ($0.00)pnpm mod:faults # one planted fault per contract rule ($0.00)pnpm mod:gallery <f-05|...|f-13|all> # failure gallery cards ($0.00)claude plugin validate --strict --json model-ledger # static scan and type check ($0.00)claude plugin test model-ledger # the mod's own tests ($0.00)bash kit/live/run.sh T1|T2|T3 [--guard on] # optional capped live task (cents)Limits (Mods reference, checked 2026-11-15)
| Limit | Value |
|---|---|
| A hook's own time for one event | 10 seconds (50 milliseconds for prompt.edit), not counting next or mods API calls other than $.clock.sleep |
Raster | columns up to 512, rows up to 256, 262,144 cells in one tree |
| Elements and text children in one tree | 20,000 |
| Text in one tree | the first 100,000 characters are drawn |
$.store | 4 MiB of JSON in total, shared by every session on the machine |
| A pane the mod opens itself | 144 columns, or 110 after the person opened it once |
Version watch list (recorded 2026-11-15)
| Item | Tested | Watch on upgrade |
|---|---|---|
| Claude Code | 2.1.325; 2.1.311 for runtime behavior | The mods API changes across point releases: rerun pnpm mod:check and pnpm mod:test, and diff the generated .claude-plugin/types/ against the previous build's |
| Type check in validate | 2.1.323 and later | Which mistakes are caught before runtime |
Stacked AbovePrompt rows | 2.1.323 and later | Whether the band still keeps next(e) |
| Price table | list prices read 2026-11-15 | Update src/pricing.ts or the price_table option when prices change |
05Hands-on lab
Lab 1: Inspect a mod, then record every step and keep the totals
Check the starter, read its register function and validate output, optionally load it live and watch hot reload, then build Increment 1 (turn.step and agent.spawn recording, $.session.usage() readings, /ledger status and export) and Increment 2 ($.state, $.store, /clear restoration), verified with pnpm mod:test and pnpm mod:check at each checkpoint. The outputs below were recorded offline on 2026-11-15 with Claude Code 2.1.325 at $0.00, except the live screens of Step 3 (Live: claude-sonnet-5-5, effort medium. Recorded 2026-11-15); loading a mod and running its commands makes no model request. Their paths start at /tmp/visual-mod-work, the folder they were recorded in; yours start where you unzipped the kit.
Acceptance checks
- pnpm mod:test --upto inc2 passes unit 17/17, Increment 1 6/6 and Increment 2 11/11
- pnpm mod:check --upto inc1 passes every required rule, 8 of 12 at Increment 1, with MLC-01 (strict validate) among them
- The validate notes list every hook and mods API call, because each call is written in full
Create the workspace and check the starter
$ bash new-workspace.sh starter ../ledger-lab cd ../ledger-lab pnpm install --frozen-lockfile pnpm mod:check --upto start pnpm mod:test --upto startPASS MLC-01 claude plugin validate --strict --json passes, and reaches every src/ module [start] not yet MLC-02 hooks.json names ./register.ts, every ledger hook is registered, and every option read is declared [Increment 3] not yet MLC-03 turn.step is an async function* that delegates with yield* next(e) [Increment 1] PASS MLC-04 every gating hook has a .catch handler [Increment 1] PASS MLC-05 $ is never destructured or aliased, and src/ is pure [Increment 1] not yet MLC-06 Raster is taken from $.ui.resolve(e) only under e.surface === 'terminal' [Increment 3] PASS MLC-07 the renderer stays inside Raster and tree limits at every width [start] PASS MLC-08 calls stay on the allowlist: no $.fs, $.process, $.http, $.env, $.mcp or $.model [start] PASS MLC-09 no code reads the subagent prompt (e.prompt) [Increment 1] not yet MLC-10 the spawn guard is off by default and logs every reroute [Increment 4] PASS MLC-11 cost is labeled an estimate from a dated price table [start] not yet MLC-12 claude plugin test passes and mounts terminal, desktop and vscode [Increment 4] 7 of 12 rules pass; every required rule passes $ node --import ./kit/register-ts.mjs kit/test.ts --upto start Tests: /tmp/visual-mod-work/ledger-lab/model-ledger (Claude Code 2.1.325, 1.5 s) PASS unit 17/17 pure modules (src/) not yet inc1 0/6 Increment 1: event logging not yet inc2 0/11 Increment 2: stored totals not yet inc3 2/12 Increment 3: the rendered pane not yet inc4 1/13 Increment 4: the command and the guard not yet sf 0/4 LAB-003 regressions for SF-1 to SF-4 Required groups pass (up to unit).Read the register function and what validate sees
$ claude plugin validate --strict --json model-ledger"./register.ts hooks: session.start, command.run{command=ledger}", "./register.ts answers its own command: command.run{command=ledger}", "./register.ts calls: $.command.register"Load the mod and watch hot reload (optional, live)
$ claude --plugin-dir ./model-ledger▐▛███▛█ Claude Code v2.1.325 ▝▜██████▀ Sonnet 5.5 with medium effort · API Usage Billing ▝▝ ▝▝ /tmp/visual-mod-work/ledger-lab Plugins Discover Installed Marketplaces Errors Stats 1 mod active · model-ledger * Loading… ▐▛███▛█ Claude Code v2.1.325 ▝▜██████▀ Sonnet 5.5 with medium effort · API Usage Billing ▝▝ ▝▝ /tmp/visual-mod-work/ledger-lab ❯ /plugin ● model-ledger: reloaded (2 hooks: session.start, command.run) ❯ /ledger ⎿ model-ledger: Model Ledger starter: this answer changed on save. Start LAB-001, Increment 1. ❯ ⏵⏵ auto mode on (shift+tab to cycle)Increment 1, event logging: the tests
$ pnpm mod:test --upto inc1Initial: Before you write Increment 1
$ node --import ./kit/register-ts.mjs kit/test.ts --upto inc1 Tests: /tmp/visual-mod-work/ledger-lab/model-ledger (Claude Code 2.1.325, 1.7 s) PASS unit 17/17 pure modules (src/) FAIL inc1 0/6 Increment 1: event logging failed: turn.step records both steps of a recorded read-and-answer turn at list prices failed: a step with no usage is counted as a gap, not priced failed: agent.spawn adds the subagent, and its steps are priced on its own model failed: the subagent prompt is never stored, only its short description failed: advisor calls are counted from serverToolUses, and the engine total shows what no step carried not yet inc2 0/11 Increment 2: stored totals not yet inc3 2/12 Increment 3: the rendered pane not yet inc4 1/13 Increment 4: the command and the guard not yet sf 0/4 LAB-003 regressions for SF-1 to SF-4 Required groups do not pass yet (up to inc1). [ELIFECYCLE] Command failed with exit code 1.Final: Once Increment 1 is in
$ node --import ./kit/register-ts.mjs kit/test.ts --upto inc1 Tests: /tmp/visual-mod-work/ledger-lab/model-ledger (Claude Code 2.1.325, 3.2 s) PASS unit 17/17 pure modules (src/) PASS inc1 6/6 Increment 1: event logging not yet inc2 2/11 Increment 2: stored totals not yet inc3 2/12 Increment 3: the rendered pane not yet inc4 3/13 Increment 4: the command and the guard not yet sf 1/4 LAB-003 regressions for SF-1 to SF-4 Required groups pass (up to inc1).Increment 1, event logging: the contract check
$ pnpm mod:check --upto inc1PASS MLC-01 claude plugin validate --strict --json passes, and reaches every src/ module [start] not yet MLC-02 hooks.json names ./register.ts, every ledger hook is registered, and every option read is declared [Increment 3] PASS MLC-03 turn.step is an async function* that delegates with yield* next(e) [Increment 1] PASS MLC-04 every gating hook has a .catch handler [Increment 1] PASS MLC-05 $ is never destructured or aliased, and src/ is pure [Increment 1] not yet MLC-06 Raster is taken from $.ui.resolve(e) only under e.surface === 'terminal' [Increment 3] PASS MLC-07 the renderer stays inside Raster and tree limits at every width [start] PASS MLC-08 calls stay on the allowlist: no $.fs, $.process, $.http, $.env, $.mcp or $.model [start] PASS MLC-09 no code reads the subagent prompt (e.prompt) [Increment 1] not yet MLC-10 the spawn guard is off by default and logs every reroute [Increment 4] PASS MLC-11 cost is labeled an estimate from a dated price table [start] not yet MLC-12 claude plugin test passes and mounts terminal, desktop and vscode [Increment 4] 8 of 12 rules pass; every required rule passesIncrement 2, stored totals
$ pnpm mod:test --upto inc2$ node --import ./kit/register-ts.mjs kit/test.ts --upto inc2 Tests: /tmp/visual-mod-work/ledger-lab/model-ledger (Claude Code 2.1.325, 3.4 s) PASS unit 17/17 pure modules (src/) PASS inc1 6/6 Increment 1: event logging PASS inc2 11/11 Increment 2: stored totals not yet inc3 2/12 Increment 3: the rendered pane not yet inc4 3/13 Increment 4: the command and the guard not yet sf 1/4 LAB-003 regressions for SF-1 to SF-4 Required groups pass (up to inc2).Show the solution discussion
Compare your hooks module with the reference after each increment: node ../labs/solutions/apply-checkpoint.mjs inc1 . (then inc2) copies it over your workspace, so commit your own work first.
turn.step stays an async generator that passes every chunk through with yield* next(e) and records the finished result; every writer calls ensureLedger first, so a ledger restores after /clear even where an organization's settings pass over classic.SessionStart.
More labs in this guide
Lab 2: Draw the ledger on three surfaces, then add the command and the opt-in guard
Build Increment 3 (the pane with a terminal Raster, the Desktop and VS Code table, the band) and Increment 4 (the full /ledger command, the opt-in guard, userConfig), replay recorded sessions offline with pnpm mod:replay, and optionally run the three live tasks.
Lab 3: Diagnose four seeded failures, finish the policy mod, and run the failure gallery
Diagnose and repair the four seeded failures from what Claude Code prints, finish the org-guard policy mod with tier('prepend') tests, write down the managed-settings controls, and run the failure gallery.
06Failure gallery
Fifteen ways this breaks, and how you will know
Twelve of these reproduce in the lab; the other three were observed in this guide's recorded runs. Learn the symptom first; it is what you will actually see.
- F-01
mod:seed sf-1ReproducibleA hook waits past the 10-second limit
- Symptom
- /ledger status hangs, then Claude Code prints "model-ledger: command.run hook skipped: ran past its 10s budget" and answers with its own fallback, "model-ledger registered /ledger but no command.run hook answered it". Live, the hook settled after 10,007 ms with no model request. The test kit prints "model-ledger's command.run hook was skipped: model-ledger: exceeded 10000ms budget".
- Diagnosis
- The seeded command awaits a promise that only the next main-loop turn.complete settles, and between turns nothing does. A hook has 10 seconds of its own time, "not counting time inside next or a mods API call other than $.clock.sleep" (Mods reference). A promise of your own counts.
- Fix
- Answer from the ledger as it stands, after reading $.session.usage() again (a mods API call, which does not count). The next turn's figures show in the next status.
- Verify
- pnpm mod:test on the repaired mod passes the SF-1 regression test.
- F-02
mod:seed sf-2ReproducibleThe pane opened at start never appears, and nothing says why
- Symptom
- With open_on_start on in a 120-column terminal, no pane appears and nothing in the transcript or band mentions it until you run /ledger open.
- Diagnosis
- A pane the person did not ask for waits for 144 columns. $.ui.open resolved "{ isPlaced: false, reason: 'unasked below 144 columns (120 now): placed when the person opens it, or when the terminal is widened to 144 columns' }", and the seeded openPane ignores what it resolves to.
- Fix
- Read isPlaced. When it is false, log the reason and put "pane not shown yet; /ledger open shows it" in the band.
- Verify
- The finished mod at 120 columns prints "model-ledger: the pane is not shown yet: unasked below 144 columns (120 now): ..." with the band notice, and /ledger open docks the pane.
- F-03
mod:seed sf-3ReproducibleRaster returned on Desktop and VS Code
- Symptom
- On 2.1.323 or later, validate --strict fails with "TS2339: Property 'Raster' does not exist on type ...". On 2.1.311, which skips the type check, nothing static: in the test kit's Desktop mount the Raster's place holds an empty box, so the bars vanish without an error.
- Diagnosis
- The hook takes Raster from $.ui.resolve(e) without checking e.surface. Only the terminal's element table has it, and the declarations type each surface's table.
- Fix
- Branch on "e.surface === 'terminal'"; Desktop and VS Code get the Box and Text table.
- Verify
- pnpm mod:check passes MLC-06, and the Increment 3 tests mount all three surfaces.
- F-04
mod:seed sf-4ReproducibleAn oversized Raster empties the pane
- Symptom
- The pane is placed and stays empty. In a live session, Claude Code prints spike-probe: ui.render hook skipped: returned the wrong shape (a tree Pane refuses: Raster "grid" columns must be a whole number from 1 to 512); the test kit prints returned a tree Pane refuses: Raster "heat" columns must be a whole number from 1 to 512.
- Diagnosis
- The seeded heat strip gives every step its own cell. A Raster takes at most 512 columns and 256 rows, and a tree at most 262,144 cells; "a tree over the nesting, element, Raster cell, or Image byte limit isn't drawn" (Mods reference).
- Fix
- Fit every Raster to the pane's bodyColumns and to one Raster's limits, and fold steps into buckets.
- Verify
- pnpm mod:check passes MLC-07, which renders 288 trees across widths, themes and session sizes.
- F-05
mod:gallery f-05Reproducibleturn.step written as a plain async function
- Symptom
- Validate fails the module: the hook on "turn.step" is not an async generator: turn.step streams, so it takes async function* ($, e, next) { ... }.
- Diagnosis
- turn.step streams. await next(e) has no stream to pass on.
- Fix
- "async function* ($, e, next)" with "const result = yield* next(e)", returning result.
- Verify
- pnpm mod:check passes MLC-03.
- F-06
mod:gallery f-06ReproducibleThe guard assigns to the frozen event
- Symptom
- On 2.1.325, validate reports "TS2540: Cannot assign to 'model' because it is a read-only property"; on 2.1.311 validate passes. On both, the guard never reroutes at runtime, and the test kit prints "hook failed closed: model-ledger: errorKind=TypeError errorChars=63 (agent.spawn; its .catch answered)" and "Attempting to define property on object that is not extensible."
- Diagnosis
- Events are deeply frozen, so "e.model = ..." throws. The .catch handler then lets the spawn go on unchanged, which is the safe outcome for a cost guard and also hides the bug unless a test checks the model.
- Fix
- "next({ ...e, model })".
- Verify
- The Increment 4 guard tests pass.
- F-07
mod:gallery f-07Reproducible$ destructured, so the scan cannot read the call
- Symptom
- Validate fails the module at "const { ui } = $": "$ itself is bound to a name (bound, passed, spread, returned or read)".
- Diagnosis
- Validate and policy mods read calls from the source as written. An alias hides ui.log from the lists a policy mod relies on.
- Fix
- Write $.ui.log(...) in full, every time.
- Verify
- pnpm mod:check passes MLC-05.
- F-08
mod:gallery f-08Reproduciblefocus: false passed to $.ui.open
- Symptom
- On 2.1.325, validate reports "TS2322: Type 'false' is not assignable to type 'true'". At runtime on both versions, the hook is skipped: "model-ledger's command.run hook was skipped: model-ledger: ui.open: focus is true or left out (host check)".
- Diagnosis
- focus, closeOnEscape and holdToasts on $.ui.open, and autoFocus on a Button, accept only true.
- Fix
- Leave the key out.
- Verify
- pnpm mod:test passes /ledger open.
- F-09Observed
borderStyle: 'rounded' draws no border
- Symptom
- The box draws without a border. Validate passes with --strict and all 63 tests pass, because the declarations type borderStyle as a string and a test reads elements, not drawn borders. Live, 2.1.325 also printed Box borderStyle "rounded" is not a border style (the styles are single, double, round, bold, singleDouble, doubleSingle, classic, arrow, dashed, quote); the Box is drawn with no border.
- Diagnosis
- "A Box whose borderStyle names anything else, such as 'rounded', draws with no border" (Mods reference). The style is 'round'.
- Fix
- borderStyle: 'round'.
- Verify
- Look at the pane in a real terminal. Nothing offline checks a drawn border.
- F-10
mod:gallery f-10ReproducibleTwo session.start hooks without a matcher
- Symptom
- The module fails to load: on("session.start") is registered twice without a matcher; the first is at ....
- Diagnosis
- One unmatched hook per event per module.
- Fix
- Merge the two into one hook, or give each a matcher.
- Verify
- "claude plugin validate --strict" passes.
- F-11
mod:gallery f-11ReproducibleA test registers a stub after its first call on $
- Symptom
- TypeError: on("turn.complete") after the test first called $: the hooks beneath the plugins are registered before that, as a module registers its hooks in register().
- Diagnosis
- The first call on $ loads the plugins, and the chain is fixed from then on.
- Fix
- Register every stub first, then call $.
- Verify
- The test passes.
- F-12
mod:gallery f-12ReproducibleA mods API stub answers a bare value
- Symptom
- On 2.1.325, validate reports TS2322 on the stub's return type. On both versions, most tests fail with "test's session.usage hook was skipped: test: returned neither { value } nor { deny }", followed by the mod's own hook failing on "no implementation for session.usage".
- Diagnosis
- A stub that stands in for a mods API call answers "{ value }" or "{ deny }"; only event stubs answer the event's own result.
- Fix
- "on('session.usage', () => ({ value: { ... } }))".
- Verify
- pnpm mod:test passes.
- F-13
mod:gallery f-13ReproducibleA policy check that throws lets the mod load
- Symptom
- Without .catch, validate passes with only a note, "gating hook without .catch: plugin.register", and the test kit shows "org-guard's plugin.register hook was skipped: org-guard: undefined is not an object (evaluating 'e.uses.env.reads')": the uploader the policy must refuse loads. With .catch, every user mod is refused with "Northstar policy check failed, so this mod was not loaded".
- Diagnosis
- A hook that throws is skipped, so a gating hook fails open. The .catch handler decides the failure outcome, and for a policy that outcome should be a refusal.
- Fix
- Keep the .catch handler, and read optional fields as optional ("e.uses.env?.reads ?? []").
- Verify
- "claude plugin validate --strict org-guard" passes, and "pnpm mod:test org-guard" passes all four tests.
- F-14Observed
--bare in claude -p loads no hooks module
- Symptom
- The mod does nothing in a print-mode run. The debug log says "hooks module spike-probe@inline not loaded: installed plugins that are not managed load no hooks module in this mode (--bare); built-in plugins load regardless".
- Diagnosis
- --bare and --safe-mode skip installed hooks modules. "The settings and flags that stop installed mods, such as disableAllHooks, --bare, and --safe-mode, don't stop built-in mods" (Mods overview).
- Fix
- Drop --bare when the mod should run.
- Verify
- The run's init event lists the plugin, and the mod's command answers.
- F-15Observed
Treating a Read(.env) deny rule as a sandbox for mods
- Symptom
- Claude's Read tool on .env is refused ("File is in a directory that is denied by your permission settings."), and a mod reads the file anyway: gallery-probe: gprobe env: $.fs.read(".env") returned 80 characters; first key NORTHSTAR_DEMO_FLAG.
- Diagnosis
- Permission rules govern Claude's tools. A mod's $.fs and $.process run as you.
- Fix
- Decide which mods may load (managed settings and a policy mod), check what a mod calls before you load it, and keep secrets out of files a mod could read.
- Verify
- "claude plugin validate --json" lists every call; a visual mod lists no $.fs, $.process, $.http or $.env.
07Assessment
Transfer task and rubric
Fork Model Ledger into Test Pulse, a mod that charts test-suite runs from a synthetic record you have not seen, tested offline on three surfaces with every behavior change opt-in.
| Criterion | 0 · Emerging | 1 · Developing | 2 · Proficient | 3 · Exemplary |
|---|---|---|---|---|
| Event correctness (OBJ-001, OBJ-002) | turn.step is not an async generator, or the mod counts runs it never observed, such as a Bash call that is not a test command | Hooks fire, but a retried run is counted twice, a subagent's run is lost, or nothing survives /clear | turn.step delegates with yield* next(e); each run is read from tool.call for Bash after next(e) returns; the cost to green comes from the steps since the last green run; state restores after /clear and a reload | Proficient, and the mod handles a red, a retried and an interrupted run as the brief defines them, with a test for each |
| Interface across surfaces (OBJ-003) | Raster reaches Desktop or VS Code, or a Raster exceeds its limits | Draws on the terminal, but the fallback loses information or a narrow width breaks the layout | Terminal Raster fitted to bodyColumns; Desktop and VS Code text fallback with the same figures; /pulse answers in one line | Proficient, and the mod says why the pane is not shown when $.ui.open waits, and a long history folds into buckets instead of growing |
| Tests (OBJ-002 to OBJ-004) | No tests, or tests that pass whatever the mod does | Tests cover events but not surfaces, or stubs break the kit's rules | "claude plugin test" passes with event tests, mounts on all three surfaces, and a regression test for one seeded mistake | Proficient, and a test proves that a secret printed in test output never reaches $.store, a log line or the /pulse answer |
| Safety and trust (OBJ-005) | A secret, prompt text or test output reaches the model, a log or the network (critical); or a hook that changes behavior is on by default (critical) | Opt-in and labeled, but the hook that changes behavior has no .catch, or trust-boundaries.md leaves out what the mod reads | Calls stay on the visual allowlist; any behavior change is opt-in with a .catch fallback; every dollar figure says estimate with its price date; trust-boundaries.md is accurate | Proficient, and the .catch outcome of any opt-in hook has a test, and trust-boundaries.md says which managed settings would allow or block the mod |
Proficiency standard: Proficient or higher on every criterion. Proposed local standard, not an official certification.
The full brief
ASM-001 assesses OBJ-001 to OBJ-005 on a fork you have not rehearsed. You receive a case for Tidewren Freight, a fictional carrier on the reserved .test domain: a synthetic record of a team's test-suite runs, a short brief, and the finished Model Ledger to fork. You build "Test Pulse", a mod that reads each test run from tool.call events for Bash, prices the model steps it took to get back to green from turn.step usage, draws a pass and fail history Raster on the terminal with a text fallback elsewhere, answers /pulse, and keeps any hook that changes behavior opt-in. You submit the mod folder with its tests and trust-boundaries.md. A grader adds hidden claude plugin test cases driven by a second synthetic record you have not seen, and runs static checks.
Each criterion is scored Emerging (0), Developing (1), Proficient (2) or Exemplary (3). Passing requires Proficient (2) or higher on every criterion and no critical failure.
Critical failures (any one fails the submission): (1) a hook that blocks, rewrites or reroutes anything and is on by default; (2) secret leakage: an environment value, a token, test output text or a subagent prompt copied into a command's answer, $.store, a log line or a network request; (3) a dollar figure presented as a bill rather than an estimate; (4) any call to $.fs, $.process, $.http, $.env, $.mcp or $.model; (5) real company or personal data outside the .test and example.com domains.
08Instructor kit
Teach it to a room
Facilitation guide and lab solutions
A 120-minute run of show across LAB-001 to LAB-003, a plan until rehearsed, with preflight checks, misconceptions to listen for and stopping rules, plus a lab solutions guide whose one-command offline check runs 34 checkpoints at $0.00.
Delivery at two sizes
Scenario designs for about 12 learners in pairs, with optional capped live tasks, and about 100 learners on the offline route only, with table facilitators and checkpoint counts at minutes 28, 62 and 104. Designs to validate in a pilot, not staffing ratios.
Dry run and observation
A proposed 60-minute observed dry run: a teach-back of how mods load and fail, a seeded failure repaired live, a facilitation drill, an adaptation and blind calibration scoring. No dry run has been held yet.
Clearance record
One record per instructor, packet version and audience, filled in only from an observed dry run and decided by an authorized person. Blank: nobody has been cleared to teach this guide.
Evaluation plan and monthly report
A five-minute diagnostic, checks during the labs, a pilot before the first cohort, privacy rules and a monthly report template with numerators and denominators. Blank until the guide is taught.
10Sources and verification
- [1]Mods overview · code.claude.comchecked Nov 15, 2026
- [2]Create a mod · code.claude.comchecked Nov 15, 2026
- [3]React to events · code.claude.comchecked Nov 15, 2026
- [4]Draw in the interface · code.claude.comchecked Nov 15, 2026
- [5]Interface gallery · code.claude.comchecked Nov 15, 2026
- [6]Use the mods API · code.claude.comchecked Nov 15, 2026
- [7]Mods reference · code.claude.comchecked Nov 15, 2026
- [8]Test a mod · code.claude.comchecked Nov 15, 2026
- [9]Troubleshoot a mod · code.claude.comchecked Nov 15, 2026
- [10]Manage mods for your organization · code.claude.comchecked Nov 15, 2026
- [11]Advisor (Claude Code) · code.claude.comchecked Nov 15, 2026
- [12]Advisor tool (Claude API) · platform.claude.comchecked Nov 15, 2026
- [13]Create custom subagents · code.claude.comchecked Nov 15, 2026
- [14]Managed settings · code.claude.comchecked Nov 15, 2026
- [15]Plugin manifest reference · code.claude.comchecked Nov 15, 2026
- [16]CLI reference · code.claude.comchecked Nov 15, 2026
- [17]Pricing · platform.claude.comchecked Nov 15, 2026
- [18]Models overview · platform.claude.comchecked Nov 15, 2026
- [19]Manage costs effectively · code.claude.comchecked Nov 15, 2026
- [20]Claude Code CHANGELOG.md (2.1.311 through 2.1.325) · github.comchecked Nov 15, 2026
- [21]npm registry: @anthropic-ai/claude-code · registry.npmjs.orgchecked Nov 15, 2026
- [22]Node.js release index · nodejs.orgchecked Nov 15, 2026
- [23]npm registry: pnpm · registry.npmjs.orgchecked Nov 15, 2026
- [24]anthropics/claude-code-playground mods README and LICENSE (commit 569c528) · github.comchecked Nov 15, 2026
- [25]Settings reference · code.claude.comchecked Nov 15, 2026
Independent work. Not affiliated with or endorsed by any vendor named in this guide.
