Claude Mods: Building Function-Hook Plugins for Claude Code

Claude Mods: Building Function-Hook Plugins for Claude Code

A field guide for CandleKeep engineers and their coding agents, written from one complete build: the /trove value dashboard, made on 2026-09-15 in plugins/trove-mod/ on branch worktree-trove-mod-experiment.

Who this book is for

Two readers:

• A CandleKeep engineer who must build or repair a mod.
• A coding agent that must write mod code without a network. Every type declaration that matters is quoted verbatim here, so the agent does not guess.

What is verified, and what is not

This book separates four kinds of statement.

Marker	Meaning
Verbatim	Copied character for character from a type declaration, a README or our own source file.
Verified	We ran it on Claude Code 2.1.272 on 2026-09-15 and saw the result.
Design doc	Stated in the "Function Hooks: Core Architecture" paper. The paper describes intent, written August 2026, before the shipped build. Where the 2.1.272 types agree, the book says so; where they differ, the book says that too, and the shipped types win.
Unknown	We did not test it. The book says so and does not guess.

The Design doc marker deserves care. The paper is a design document, not a reference. It predates the build by a month, its vocabulary is the vocabulary the shipped API uses, and several of its constructs shipped exactly as written. A few did not. Never quote it as the current contract without checking claude-code.d.ts.

The function-hook API is early access. The declaration file states it plainly, verbatim:

// EARLY ACCESS: this surface may change between releases without notice.
// Written by `/plugin-types`; regenerate with that command after an update
// rather than editing. The first line names the Claude Code version that
// wrote it. TypeScript 5.4 or newer reads it.

Treat every signature in this book as correct for the version named in the header of your own generated claude-code.d.ts, and for no other version.

The sources behind every claim

Source	What it gives
"Function Hooks: Core Architecture", Alice Poteat, Anthropic, August 2026, 8 pages	The design document attached to issue 91870. The only design document that exists. Gives the vocabulary, the algebra, the five placements, the engine-interface fold, and the enterprise model.
types/claude-code.d.ts, written by Claude Code 2.1.271	The full declarations. 10.7k lines. The authority on every signature.
anthropics/claude-code tree main/mods README	The mods concept, the testing kit, the noun contracts.
mods/diff source	The reference pane mod, built into Claude Code.
sezaakgun/cc-arcade	The first community plugin that draws an interactive surface above the prompt.
plugins/trove-mod/hooks/register.tsx	Our own complete mod. 713 lines. The worked example in Chapter 8.
anthropics/claude-code issue 91870	The announcement thread.

How to read it

One topic per chapter. Chapter 10 is the rule list: if you read one chapter before you write code, read that one. Chapter 8 is the complete worked example. Chapter 12 holds every link.