Mods reference changedplugins/mods/reference
Upstream edited this page at 25 Oct 2026 14:35 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 25 Oct 2026 14:37 UTC.
Upstream edited
Recorded here
Lines+10added
Lines−2removed
From line
17
where the diff opens
First seen
1 Oct 2026
this site's first read of the page
Recorded edits39to this page, all time
#### `e.layers` and `e.source` on `settings.read`
The whole hunk
from line 17, old and new numbered
/
from line 17
1717| `.claude-plugin/plugin.json` | Yes | The plugin [manifest](https://code.claude.com/docs/en/plugins/manifest-reference.md). Mods add no required fields. |
1818| `hooks/hooks.json` | Yes | `modules`: an array with one path, relative to this file, to the hooks module, as in `"modules": ["./register.js"]`. Can also hold [settings hooks](https://code.claude.com/docs/en/hooks.md) under `hooks`. |
1919| The hooks module, such as [`hooks/register.js`](https://code.claude.com/docs/en/plugins/mods/create#write-a-mod-yourself) | Yes | The mod's entry point. Exports `register(on, options)`. Named `.js`, `.mjs`, `.cjs`, `.jsx`, `.ts`, `.mts`, `.cts`, or `.tsx`. An ES module. |
20| [`types/index.d.ts`](https://code.claude.com/docs/en/plugins/mods/interface#declare-the-values), named by `types` in the manifest | When the mod uses `$.state` or adds a namespace to the mods API | Declares `PluginState` values and any namespace the mod adds |
20| [`types/index.d.ts`](https://code.claude.com/docs/en/plugins/mods/interface#declare-the-values), unless `types` in the manifest names another path | When the mod uses `$.state` or adds a namespace to the mods API | Declares `PluginState` values and any namespace the mod adds. To leave `types` out of the manifest, you need v2.1.299 or later. |
2121| Files whose names end in `.test.ts` or `.test.tsx` | No | Tests that [`claude plugin test`](https://code.claude.com/docs/en/plugins/mods/test#write-a-test) runs |
2222
2323`register` receives `on` and `options`. `options` holds the values of the [`userConfig`](https://code.claude.com/docs/en/plugins/components#user-configuration) fields the manifest declares, with defaults filled in.
from line 106
106106
107107### Commands and configuration
108108
109Command and configuration events fire when a command runs or is listed, and when a `/config` row is shown or changed:
109Command and configuration events fire when a command runs or is listed, when a `/config` row is shown or changed, and on a settings read:
110110
111111| Event | Fires when | A hook can return |
112112| :- | :- | :- |
from line 114
114114| `command.describe` | Once for each command, for the command list | `{ description, argumentHint, isHidden }` |
115115| `config.set` | A `/config` row is about to change | `next({ ...e, value })` or `{ deny: reason }` |
116116| `config.describe` | Once for each `/config` row | `{ label, description, isHidden }` |
117| [`settings.read`](https://code.claude.com/docs/en/plugins/mods/events#settings-read-hook) | A mod calls [`$.settings.read`](https://code.claude.com/docs/en/plugins/mods/api#reach-files-processes-and-the-network), or Claude Code builds the session's merged settings | `next(e)`, `{ value }`, or `{ deny: reason }` |
118
119#### `e.layers` and `e.source` on `settings.read`
120
121* **`e.layers`**: one `{ source, settings }` object for each source in use that holds settings, lowest [precedence](https://code.claude.com/docs/en/settings.md#settings-precedence) first. See [What a `settings.read` hook receives](https://code.claude.com/docs/en/plugins/mods/events#settings-read-receives).
122* **`e.source`**: the one source a mod asked for, as in `$.settings.read({ source: 'policy' })`. Absent on Claude Code's own read and on any other read of the merged settings
123
124On `settings.read`, the event firing on Claude Code's own read and the `e.layers` field require Claude Code v2.1.304 or later. For when the hook runs and what the hook can return, with an example, see [Change or refuse a settings read](https://code.claude.com/docs/en/plugins/mods/events.md#settings-read-hook).
117125
118126### Turns
119127
No line in this hunk matches that.