Follow Discord
Sweep 06 Nov 2026 · 01:32Z Build v2.1.319 537 read Stable v2.1.311 Latest v2.1.318 Next v2.1.319 Feeds RSS JSON llms.txt llms-full.txt Unofficial
Home / Reference / Mods Guide
Mods API

The whole surface.

Every noun, verb, event and type a Claude Code mod can reach, with the signature and the doc comment Claude Code wrote for it. Anthropic's Mods reference covers the same surface a table at a time. This is every declaration in full, and none of it is written by hand here: the release pipeline pulls the declarations out of the shipped binary and this section renders what it found.

Search to find a name. The three pages under it are the same symbols in full, with the source text.

Symbols866every one, in the index below
Mined from2.1.319the shipped binary
Machine readableapi.jsonin pages, sized for an agent's fetch; api-full.json is the whole document
What changed

v2.1.319

+9 added · 4 removed · 3 changed · 3 docs only 5 may break Every release since v2.1.259
  1. TypesEvery declaration in the file, verbatim, with the doc comment above it.
  2. ModelApiError type Which kind of API failure ended a model call (a completion, a fork), in the word Claude Code classifies every API error with (StopFailure's).
  3. ModelCompleteInput type What a hook on model.complete reads as e: the request with its text as strings, as it always was, and the caller's blocks beside them.
  4. ModelCompleteOptions type Options of $.model.complete: what is no part of the request, so no hook on model.complete reads it on e.
  5. ModelCompleteRequest type What $.model.complete takes.
  6. ModelCompleteResult type What one model call resolves to: the reply when the model answered (isAnswered), else which of three things left it without text (reason).
  7. ModelEffort type How hard a request asks the model to think, by the levels the engine and turn.step name: low to max, xhigh between high and max.
  8. ModelForkRequest type What $.model.fork takes.
  9. ModelForkResult type What $.model.fork resolves to: a completion's result (ModelCompleteResult) or that there was nothing to fork yet.
  10. ModelTextBlock type One block of text in a $.model.complete request's prompt or system: sent as written, in the order given, and markable for the prompt cache.
  11. ModelUsage type What one model call cost, as the API counted it: the four token counts in the API's spelling, summed over the call's responses when it made several.
  12. Namespace type The prefixes a glob may name: one or more whole leading segments of an event name (tool of tool.call), derived, plugin nouns included.
  13. NarrowDepth type How many object or array levels a matcher narrows e through, counted as a tuple's length: the runtime's own limit, which refuses a deeper matcher.
  14. Narrowed type e in a matched hook: the members of the argument union E matcher P can match, each with the keys P names narrowed to what a match implies.
  15. NarrowedByAny type A value of declared type V under a one-of, folded over the tuple into Found: the union of what each alternative narrows V to (NarrowedByOne).
  16. NarrowedByOne type A value of declared type V under one matcher node Q that is not a one-of, member of V by member; a member that cannot match is never.
  17. NarrowedMember type One object member E under object pattern P, D levels down: never when a key of P is impossible on it (ImpossibleKeys), else E narrowed.
  18. NarrowedValue type A value of declared type V where the matcher gives Q, D levels down: NarrowedByAny under a one-of (an array), NarrowedByOne otherwise.
  19. Negation type ! before a name or a glob: every event except the ones it selects. !* would select none, so it is no pattern.
  20. Next type The rest of the chain, as one hook receives it: made once per dispatch per hook, frozen; next(e) resolves to the downstream result.
  21. NextBudget type The budget the code reading next.budget runs under: the whole allowance and what is left of it now, plain data read fresh on each access.
  22. NextResult type What next(e) resolves to for event N: the event's result, except at engine.create, where the steps beneath return $ as built so far.
  23. NextResultFor type What next(e) resolves to once e.tool is the literal T: on tool.call the result typed for that tool; on every other event, O as declared.
  24. NoArgs type The argument of a call on $ that takes nothing ($.session.cwd()): an object with no keys.
  25. NoArgsEvent type The events whose argument is exactly NoArgs (session.cwd, a declared plugin noun's () => ...); their overloads come last (LateOverload).
  26. NoEngineInterface type What an engine.create hook receives as $: nothing. Every property reads as never, so $.model inside the hook is a compile error.
  27. NonEmpty type Array type V, of element Item, once some element of it is known to match: a tuple of at least one Item, readonly when V is.
  28. NotificationHookInput type
  29. NotifyOptions type Options of $.ui.notify.
  30. NounEvent type The declared plugin nouns' methods as event rows (NounEventRow), one per <noun>.<method> that is a function; a member that is not is no event.
  31. NounEventName type The name of a declared plugin noun's event (voice.speak).
  32. NounEventOf type The events of the plugin nouns declared on EngineInterface, by name: the argument of each <noun>.<method>. Empty until a plugin declares a noun.
  33. NounEventResult type The result of a declared plugin noun's event as its hooks see it: { value } (the method's answer) or { deny }.
  34. NounEventRow type One method of a declared plugin noun as an event row: its event's name, argument (the method's first parameter) and value (its awaited result).
  35. NounValueOf type What each declared plugin noun's method answers (the value of its event's result), by event name.
  36. On type Registers hook on the events pattern selects: one by name, every one under a namespace (classic.*), all (*), or all but some (!tool.*).
  37. OnScreen type The part of a transcript message the surface that drew it has on screen: units first to last of the message's of, counted from its start.
  38. OpenMatcher type The keys a variant with a string index signature (an MCP tool's input) takes beyond its own: another variant's key as typed there; others free.
  39. OpEventName type The name of a call on $ the host serves, as an event.
  40. OpEventOf type The calls on $ the host serves, as events: e is the call's argument as it crosses to the host, and every one is hookable by name and by on("*").
  41. OpEventResult type The result of a call on $ as its event's hooks see it: { value } (the call's answer) or { deny }.
  42. OpValueOf type What each call on $ answers (the value of its event's result), by event name.
  43. OrderedOverloads type One call signature per event in Names, intersected, the ambiguous ones (LateOverload) after the rest: next for a hook covering several events.
  44. Origin type Who raised a dispatch, as next.origin holds it: the calling plugin's name and the tier it sits in; the engine reads engine in core.
  45. Overloads type One call signature per event in Names, intersected into an overload set.
  46. PaneCloseArgs type The argument of $.ui.close: the pane to close ({ id }). origin is the engine's to set: a plugin's call reads plugin at the hooks.
  47. PaneCloseInput type The input of ui.close: the pane closing and why (PaneCloseOrigin). Closing an id that is not open does nothing.
  48. PaneCloseOrigin type Why a pane closes, as the engine stamped it at ui.close.
  49. PaneOpenArgs type The argument of $.ui.open: which pane, its title, whether it asks the person's keyboard, its dialog manners, its size: rows inline, columns docked.
  50. Pattern type What on(pattern, hook) and next.is(pattern, e) take: an event's name, a glob (*, classic.*), or a negation of either (!tool.describe).
  51. PatternOver type The patterns next.is takes in a hook covering the events N: their names, *, a glob over one of their namespaces, or a negation.
  52. PermissionBehavior type
  53. PermissionDeniedHookInput type
  54. PermissionMode type Permission mode for controlling how tool executions are handled. 'default' - Standard behavior, prompts for dangerous operations. 'acceptEdits' - Auto-accept file edit operations. 'bypassPermissions' - Bypass all permission checks (requires allowDangerouslySkipPermissions). 'plan' - Planning mode, no actual tool execution. 'dontAsk' - Don't prompt for permissions, deny if not pre-approved. 'auto' - Use a model classifier to approve/deny permission prompts.
  55. PermissionRequestDecision type A classic.PermissionRequest answer's decision, as the classic hook's hookSpecificOutput.decision: allow (with a rewrite or rules) or deny.
  56. PermissionRequestHookInput type
  57. PermissionRuleValue type
  58. PermissionUpdate type
  59. PermissionUpdateDestination type
  60. PermissionUpdates type The permission rules a PermissionRequest allow may add: the shape of the request's own permission_suggestions (the SDK's PermissionUpdate list).
  61. PlanModeDetail type What the engine knew as it made a plan-mode reminder: which of its two wordings the row carries, where the plan is kept, whether one is there.
  62. PlanModeExitDetail type What the engine knew as it made the note that plan mode has ended: where the plan is kept, whether one is there.
  63. PlanModeReentryDetail type What the engine knew as it made the note that plan mode is entered again: where the plan of the earlier planning is kept.
  64. PlayOptions type How $.audio.play plays a clip: looped until signal aborts, or once.
  65. PluginNoun type The nouns a plugin declared on $ by merging into EngineInterface; never one the engine's own events are under (tool, session, ui).
  66. PluginOptions type A plugin's options as register(on, options) receives them: the values of the fields its manifest's userConfig declares, defaults filled in.
  67. PluginRegisterInput type The input of plugin.register: one hooks module the engine is about to load, read off its manifest and its scanned source. Every field is pinned.
  68. PluginRegisterResult type What a plugin.register hook returns and what next(e) resolves to: { allow: true } from core, or { refuse: reason }.
  69. PluginRegisterUses type What a hooks module uses, as the host scanned its source before loading it: the same lists claude plugin validate prints and the host's rule reads.
  70. PluginStamp type Whose element: the plugin whose hook drew it, stamped by the runtime as the tree leaves it; a Box's or Text's group, a Client's or Raster's own.
  71. PluginState interface The named values plugins keep in the session ($.state), by plugin name then key, for declaration merging; empty by default.
  72. PostCompactHookInput type
  73. PostModelSwitchHookInput type
  74. PostToolBatchHookInput type Hook input for the PostToolBatch event. Fired once after every tool call in a batch has resolved, before the next model request. PostToolUse fires per-tool and may run concurrently for parallel tool calls; PostToolBatch fires exactly once with the full batch.
  75. PostToolBatchToolCall type
  76. PostToolUseFailureHookInput type
  77. PostToolUseHookInput type
  78. PreCompactHookInput type
  79. PreModelSwitchHookInput type
  80. PressedLink type The link a press landed on: one a Markdown drew, pressed where the surface reports presses (a plain click in the fullscreen terminal).
  81. PreToolUseDecision type The decision of a classic.PreToolUse result: allow, ask, deny, or none.
  82. PreToolUseHookInput type
  83. PreToolUseResult type What a classic.PreToolUse hook returns: one of allow, ask, deny, or none of them, which passes the call on to the normal permission flow.
  84. ProcessRunInit type Options of $.process.run.
  85. ProcessRunResult type What $.process.run resolves with once the child has exited.
  86. ProcessSpawnChunk type One piece of a spawned child's output as $.process.spawn streams it: which pipe it came from, and the text.
  87. ProcessSpawnRequest type The argument of $.process.spawn(request), and the e its hooks see: the command by its argument vector and how the child is started.
  88. ProcessSpawnResult type How a spawned child ended, as the stream of $.process.spawn returns it once every piece has been read: its exit code, or the signal that did it.
  89. PromptAttachmentDetailOf type The facts prompt.attachment pins under e.detail, by attachment type: what the engine computed for the row, as it rendered the row's text.
  90. PromptAttachmentInput type The input of prompt.attachment: one message the engine injects into the conversation for the model on its own, as a request is about to carry it.
  91. PromptAttachmentOrigin type Who authored the text an injected attachment carries, as the engine knows it from the attachment itself; a closed set, pinned on the event.
  92. PromptAttachmentResult type What a prompt.attachment hook returns: the text the model reads for that attachment, or null to leave the attachment out of the request.
  93. PromptAutocompleteInput type The input of prompt.autocomplete: the prompt box as the person left it and the token at its cursor, which a taken suggestion replaces.
  94. PromptAutocompleteResult type What a prompt.autocomplete hook returns and what next(e) resolves to: the rows the plugins add to the typeahead for the token.
  95. PromptAutocompleteSuggestion type One row a prompt.autocomplete hook adds to the prompt box's typeahead: what taking it writes, what the row shows, and a dim line beside it.
  96. PromptBox type The person's prompt box as it stands: the draft and where the cursor is in it; what $.prompt.read() resolves and $.prompt.fill hands back.
  97. PromptChangeInput type The input of prompt.change (prompt-change/): the prompt box after a change of its text that no prompt.edit carried, and who made it.
  98. PromptChangeOrigin type Who changed the prompt box at prompt.change, as the engine stamps it where the text is written; a matcher narrows on its kind.
  99. PromptChangeResult type What a prompt.change hook returns and what next(e) resolves to: { text }, echoed by core; a hook's own value changes nothing.
  100. PromptComposeArgs type What a plugin passes $.prompt.compose: the facts it wants composed for, each one it leaves out read off the session (its model, its tools).
  101. PromptComposeInput type The input of prompt.compose: the facts a system prompt is composed from, each already resolved by the engine, at the moment it renders one.

What the file says about itself

Claude Code writes the declarations with an introduction at the top, and this is it, reproduced as it ships. Until Anthropic published their mods docs with 2.1.287, it was the only guidance that came with the surface.

EARLY ACCESS: this surface may change between releases without notice. Written by the engine each time it loads a mod from a folder the person owns, beside that mod as .claude-plugin/types/claude-code/index.d.ts; written again after an update rather than edited. The first line names the Claude Code version that wrote it. TypeScript 5.4 or newer reads it. `claude plugin validate <dir>` is the other half: it reads a plugin's manifest and its hooks module's source the way the engine will and reports what the module hooks and calls and everything the engine would refuse, before any session loads it.

What is here: the module a hooks module may import types from,

import type { Register, On, EngineInterface } from 'claude-code'

(at run time the import is empty), and the globals a hooks module has: `h` and `Fragment` (what JSX compiles against), the JSX namespace, and the environment's web APIs (URL, TextEncoder, AbortController, crypto.subtle, ...). A hooks module runs in an environment of its own: no DOM, no Node. The module, and every file it imports from the plugin, is named .ts, .tsx, .jsx, .js, .mjs, .cjs, .mts or .cts (a file named otherwise is not loaded) and is an ES module whatever its suffix: there is no `require`. A file of the plugin is imported with an `import` declaration. A module holding `import()` does not load. The elements a render hook draws with (`Box`, `Text`, `Button`, ...) are not globals: they come from the surface's table,

const { Box, Text } = $.ui.resolve(e)

Also here: 'claude-code/testing', the kit a plugin's *.test.ts and *.test.tsx files import under `claude plugin test <dir>`, which runs each in an environment like the one a plugin's hooks run in (no fs, network or process), the plugin loaded from the folder by the engine's own host: `test(name, async ($, on) => { ... })`, where `$` is the engine's own and the hooks `on` registers sit beneath every plugin; with describe, expect, tier, and `mock`, whose clock, store and env answer those nouns beneath the plugins from memory. `$.ui.mount` draws a component through the plugin on the surface the test names (terminal, desktop, vscode or mobile: never assumed) and hands back the drawing to read and act on by key: find an element, press a Button, type into an Input, drive a `Client`'s module (keys, pointer, posts, its frame clock), each act typed by that surface's element table, so one test body run over several surfaces covers the mod's hooks and description on each. It exercises the mod (its hooks, the tree they return under each surface's rules, its `Client` modules), never a surface's paint (Ink's, the desktop page's):

test('notes add up on every surface that takes input', async $ => {
  for (const surface of ['terminal', 'desktop'] as const) {
    const ui = await $.ui.mount({ plugin: 'notes', surface, ...BAND })
    await ui.input({ key: 'new', text: 'milk' })
    expect((await ui.find({ key: 'count' }))?.text).toBe('1 note')
    await ui.key({ key: 'down', in: 'list' })
    await ui.unmount()
  }
  for (const surface of ['terminal', 'desktop', 'vscode', 'mobile'] as const) {
    const ui = await $.ui.mount({ plugin: 'notes', surface, ...HINT })
    expect(await ui.find({ type: 'Text', text: /notes/ })).toBeDefined()
    await ui.press({ key: 'dismiss' })
  }
})

Typing a plugin against it:

export const register: Register = (on, options) => { ... }

or, in a .js module,

/** @type {import('claude-code').Register} */
export const register = (on, options) => { ... }

A tsconfig.json (or jsconfig.json) that fits a hooks module:

{
  "compilerOptions": {
    "target": "es2023", "lib": ["es2023"], "types": [],
    "module": "esnext", "moduleResolution": "bundler",
    "strict": true, "noUncheckedIndexedAccess": true,
    "noEmit": true, "skipLibCheck": true,
    "jsx": "react", "jsxFactory": "h", "jsxFragmentFactory": "Fragment"
  },
  "include": [".claude-plugin/types", "hooks", "types", "tests"]
}

".claude-plugin/types" is where the engine lays this file (claude-code/) and, beside it, this build's built-in tools (claude-code-tools/), the MCP tools connected when the mod last reloaded (claude-code-mcp/) and one entry per plugin the mod's plugin.json lists under "dependencies" (that plugin's own contract): what it adds to `$` in engine.create, so a plugin you depend on is typed with nothing copied (the include above takes the whole folder). "hooks" is the plugin's hooks/ folder, "types" its own contract and "tests" its test files. `lib` names no DOM: the environment has none, and its `Text` would shadow the element. A mod with no tsconfig of its own has these options without writing them: the engine gives it a tsconfig.json that extends .claude-plugin/types/tsconfig.json, which carries them with that folder as the one type root.

A plugin that adds a noun to `$` ships its own contract: a .d.ts its plugin.json names as "types", exporting the noun's types at its top level and declaring the noun on the engine's interface,

export type Topo = { ... }
declare module 'claude-code' {
  interface EngineInterface { topo: Topo }
}

with no import or reference, its exported names led by the noun's PascalCase name; the plugin's own hooks module imports them from it.

Where this comes from

Claude Code carries its own type declarations for the hooks runtime. From 2.1.287 it writes them into .claude-plugin/types/ each time it loads a mod from --plugin-dir, and before that /plugin-types wrote them on request. They are not in the npm package as a file and not in the JavaScript bundle either: Claude Code decompresses an asset embedded in the binary. So documenting the surface used to mean installing a build and running it by hand, which is why nobody did it twice.

The release pipeline reads that asset straight out of the binary it already downloads, parses it, and writes a JSON document beside the rest of the release data. This section renders that document. Which means it is never a release behind, and nobody has to remember anything.

The prose about how to use any of this, what the calls cost, and which ones do not behave the way their shape suggests is the Mods Guide. This section is the inventory.

Mined from build 2.1.319 on 6 Nov 2026 . The declarations are Claude Code's own writing about itself, reproduced here; everything around them is this site's.

Feedback