Where these rules and the surrounding code say nothing, choose the simplest thing that works: a little repetition is better than an abstraction with one caller.
Loading rules
Claude Code reads hooks/register.tsx and every file it imports before loading the plugin, and refuses code it
cannot follow. Anthropic's plugin directory is stricter: it lists the plugin's capabilities from the engine calls in
register.tsx alone, and refuses $ handed to a function in another file, even though Claude Code accepts that.
claude plugin validate applies none of the directory's rules; only the developer portal's Validate does. The
engine's API is declared in .claude-plugin/types/claude-code/index.d.ts, which Claude Code writes when it loads
this folder.
- Only
register.tsxnames$. A hook that needs the engine beyond a direct call bindsconst host = hostOf($)as its first statement and passeshoston. Features takehost: Host(core/host.ts), never$. This follows Anthropic's owncode-modernizationplugin. - An engine call a feature needs is a member of
Hostand one line inhostOf: a closure making a single literal call,read: (path) => $.fs.read(path). An overloaded method gets one member per form Delta uses (session.apiMessages), and an environment variable one member per name (env.os), so every call stays literal. Bind aHostper hook call and keep none in a module variable:$carries the calling hook's context. - In
register.tsx,$goes only tohostOfandlogHookFailure, which are top-level function declarations there. Write each call literally:$.noun.method(...),$.env.get('LITERAL'), and$.statereferences with a literalpluginandkey. Don't give anything else the name of$,on, or a hook's third parameter: the directory reads those names as the engine's throughout the file. - Import types with
type(import type { Host }, ortype Hostin a mixed import). Each file is compiled alone, so an unmarked type import fails at load with "Export named … not found". - Import only the plugin's own files: no
import(), Node or DOM APIs, or npm packages.
Where code goes
register.tsxholds theon(...)registrations, each with its.catch. A handler longer than a few lines is a function in its feature's module, typede: HookEvent<'tool.call'>, next: HookNext<'tool.call'>. An event a subagent's loop also raises routes one.agentIdtosubagents.ts.- Each feature has a folder under
hooks/(watch/,recording/,sharing/, …) holding its modules and their unit tests;core/holds what every feature uses, andtesting/the test fake. New code goes in the module for its feature; each module's header says what it holds (head -6 hooks/*/*.ts*). Logic without aHostsits in a module of its own, which tests call directly. - Pass
hostto helpers. The narrower hostsSetupEnv,Interaction,AuthenticationHostandUpdateHostare built from it so tests can substitute them; add no others. - Export only what another module or a test uses. A module variable others read is an
export let, with no getter. - Run a Delta command through a
delta-cli.tsfunction (sign-in and updates go through their hosts). It labels the command as Claude Code's for Delta's telemetry and checks the answer; the tests flag an unlabelled command.
State
- A module variable lives in the module that changes it. If another module needs to change it, move the variable
there, or call a function of its module that does a whole step (
startSharemarks the share in flight, shows its progress and schedules it). A function that only assigns one field adds indirection and hides nothing. SessionState,requestsandactivationinsession-state.tsare shared per-session records: features write their fields, andsession-state.tsclears them.- Key per-session state by session ID and clear it from the
session.endhandler. Keep process-wide state for caches that really span sessions. - Model a lifecycle with phases as a discriminated union changed only by named transitions, as
feed.connectioninwatch.tsis; other modules askliveFor,watchedSessionorwatchStatus. Re-read the phase after eachawait. Independent flags stay flags. - After an
awaitthat can yield to another event, check the work is still current:stillActive(session)for the recorded session,feed.revisionfor the watch. - The band's drawing state stays in
band.tsxandrows.tsxmodule variables, redrawn withhost.ui.invalidate().$.stateatoms survive a hot reload, so moving it there is its own decision.
Types
- Use
typealiases for object shapes; an alias assigns to the engine'sJsonValue, an interface doesn't. - Parse untrusted input as
unknown(const value: unknown = JSON.parse(text)) and narrow it with thejson.tsguards andcommandErrorFromEnvelope. A validator is a type guard or an assertion function.anyappears only in tests, fakes and generated fixtures. - Use
asforas const, or with a comment saying why the type holds. Read saved bindings throughstoredBindingandstoredChildBinding. - Narrow locally rather than using a
!whose reason is far away; a!right after its own check is fine. - End a
switchover a union withdefault: { const unreachable: never = value; … }.
Errors
- Name error classes
…Error, and add one only when a caller checks it withinstanceof. - Throw in feature code and turn errors into the engine's answer at the hook. A failure is a member of a tagged
union (
{ kind: 'none'; reason }), not a bare string. - Give every hook that can block or refuse an explicit
.catch. Hooks that record or observe fail open (logHookFailure, thennext(e)), so recording never blocks someone's work;prompt.submitfails closed. - An empty
catchor.catch(() => {})that drops a side effect's failure has a comment saying why that is safe. A read that treats failure as absent, a parser's fallback, stopping a child process, and waiting for something to finish need none. - Show a person
errorText(error);String(error)prefixes the class name, which suits debug logs only. - User-facing text is product copy: change it only on purpose.
Names and comments
$is the engine,hosttheHostbound from it, andethe event;sessionis a Claude session ID,threada Delta thread ID,agentIda Claude subagent ID.- A comment moves with its code and stays true there. Check a claim about the engine against its types or
claude plugin validatebefore writing it.
Tests
- Unit-test pure functions directly, in a file named after their module, beside it.
- Test behaviour with the engine's test kit and
fakeThreads, in thedescribefor its feature inregister.test.tsor a feature's existing engine test file. Each test file runs in a process of its own that warms the plugin up again, so a new engine test file adds CPU that makes CI's timed tests flaky. - Let the plugin run with
fake.settle()andfake.advance(ms), which wait until it has gone quiet, notfake.clock.settle()orfake.clock.advance(ms), which a loaded machine can outlast. Wait for one specific condition withfake.settleUntil(…). - Reuse the helpers in
fake-thread-commands.ts, and move a helper there once a second test file needs it. - Assert on
ui.findresults: a missed match isundefined, not a failure.
Formatting
There is no formatter: match the code around you, and keep formatting changes out of structural commits.
- No semicolons, 2-space indentation, trailing commas on multiline lists.
- Single quotes, or double quotes when the text contains an apostrophe.
- Names inside an import's braces sorted alphabetically, ignoring
type. - Wrap code past about 120 columns at a natural break. A user-facing string stays on one line, so it can be found by searching for its text.
Before you finish
- Run the checks in
AGENTS.md.claude plugin validate .lists nogating hook without .catch. - In a refactor, the hooks
validatelists and the$calls in source (grep -rohE --include='*.ts*' '\$\.[a-z]+\.[a-zA-Z]+' hooks | sort -u) stay the same. - Any change to user-visible text (
host.ui.log,{ drop },{ text }, band strings) is intended.