@cmodjs/core 0.1.14 → 0.2.1

package/docs/commands.md

@@ -22,12 +22,13 @@ Creates a mod in `./<name>`: a `defineMod` with one hook, one pane, and one rend
 ### cmod link
 
 ```text
-cmod link [path] [--yes]
+cmod link [path] [--yes] [--option key=value]...
 ```
 
 Loads the checkout at `path` (default: the current folder) in every new Claude Code session, in place of the installed mod. Installs the cmod plugin when Claude Code lacks it, unless the checkout is cmod itself. Then installs the checkout's packages, builds the program `cli/` declares into `~/.local/bin`, writes the folder into `CLAUDE_CODE_PLUGIN_DIRS` in the `env` block of Claude Code's `settings.json`, and runs the checkout's install step. A session that is already running loads it after `/reload-plugins`.
 
 - `--yes` approves the mod's install and uninstall commands without asking.
+- `--option key=value` sets one of the mod's options through `claude plugin configure`, once per option. It refuses a key the mod does not declare, and names the keys it does ([options.md](options.md)).
 
 ### cmod unlink
 
@@ -47,27 +48,29 @@ Runs every check this machine can run on the mod at `path` (default: the current
 
 1. Installs its packages.
 2. Checks its layout.
-3. Checks that each step runs a script.
-4. Checks its imports.
-5. Looks for prebuilt binaries outside `cli/`.
-6. Bundles the hooks module as `cmod publish` does, and names each reason a bundle fails.
-7. Validates it with Claude Code, `claude plugin validate --strict`.
-8. Type-checks it with `tsc`, with `tsconfig.json`, and then with `tests/tsconfig.json` when it exists. `cmod new` writes both: the root config leaves Bun out of `src/`, which runs inside Claude Code, and the tests config adds `bun-types`, so a test can run a real program with `Bun.spawn` or read files with `node:fs`. When `.claude-plugin/types/` is missing, as in a fresh clone or in CI, Claude Code writes it first: cmod loads the mod in one `claude -p` run with a config folder of its own and no model to reach, so the run sends nothing.
-9. Lints it with `oxlint`.
-10. Runs, with `bun test`, every test file that does not import `claude-code/testing`.
-11. Runs, with `claude plugin test`, the test files that import `claude-code/testing`. It skips this when none does.
-12. Checks its name against other plugins. Only a project plugin, in `.claude/skills/<name>/` of a repository, runs this check: it fails when an installed or linked plugin has the same name and hides the project plugin. Any other mod passes it at once.
+3. Checks that each step runs a script, and prints the permissions the person grants at install and can grant later, as the person reads them ([permissions.md](permissions.md)). It fails a `hooks/register.ts` that calls `registerPermissionCheck` without `"approve": true`.
+4. Writes the options `defineMod` declares into `.claude-plugin/plugin.json` `userConfig`, keeping the file's own formatting, so Claude Code shows them in `/config` ([options.md](options.md)). It loads `hooks/register.ts` to read them, without starting the mod.
+5. Checks its imports.
+6. Looks for prebuilt binaries outside `cli/`.
+7. Bundles the hooks module as `cmod publish` does, and names each reason a bundle fails.
+8. Validates it with Claude Code, `claude plugin validate --strict`.
+9. Type-checks it with `tsc`, with `tsconfig.json`, and then with `tests/tsconfig.json` when it exists. `cmod new` writes both: the root config leaves Bun out of `src/`, which runs inside Claude Code, and the tests config adds `bun-types`, so a test can run a real program with `Bun.spawn` or read files with `node:fs`. When `.claude-plugin/types/` is missing, as in a fresh clone or in CI, Claude Code writes it first: cmod loads the mod in one `claude -p` run with a config folder of its own and no model to reach, so the run sends nothing.
+10. Lints it with `oxlint`.
+11. Runs, with `bun test`, every test file that does not import `claude-code/testing`.
+12. Runs, with `claude plugin test`, the test files that import `claude-code/testing`. It skips this when none does.
+13. Checks its name against other plugins. Only a project plugin, in `.claude/skills/<name>/` of a repository, runs this check: it fails when an installed or linked plugin has the same name and hides the project plugin. Any other mod passes it at once.
 
 `cmod check` fetches `tsc` 7.0.2 and `oxlint` 1.86.0 into the cmod store the first time. It ends with a count of passed, failed, and skipped checks, and exits 1 when one failed.
 
 ### cmod try
 
 ```text
-cmod try <owner/repo | path>... [--yes] [--home <folder>] [-- claude arguments]
+cmod try <owner/repo | path>... [--yes] [--option key=value]... [--home <folder>] [-- claude arguments]
 ```
 
 Starts one throwaway Claude Code session with mods set up, for trying a mod by hand or testing it with an agent. Installs each mod's packages, installs the cmod plugin when Claude Code lacks it, and runs each mod's install step after asking consent. Then starts one Claude Code session with every mod loaded through `--plugin-dir`.
 
+- `--option key=value` sets one option of the mod. With several mods, write `--option <mod>.key=value`.
 - The session runs with a new home folder, so it sees only the mods named here and changes none of your Claude Code settings, mods, key bindings, or history. The folder is deleted when the session ends.
 - The session stays logged in as you, with no login screen:
   - On macOS, Claude Code reads your login from the keychain, which `cmod try` links into the new home as `~/Library/Keychains`. Deleting the home removes only the link.
@@ -87,15 +90,15 @@ Starts one throwaway Claude Code session with mods set up, for trying a mod by h
 cmod publish [path] [--dry-run]
 ```
 
-Releases the mod at `path` (default: the current folder) at the version in its `plugin.json`:
+Releases the mod at `path` (default: the current folder) at the version in its `plugin.json`. It refuses a `plugin.json` whose `userConfig` differs from the options `defineMod` declares, and says to run `cmod check` and commit `.claude-plugin/plugin.json`.
 
 1. Builds the release from the committed files, leaving out `cli/`, `.github/`, and `.claude/`. A `"files"` list in `package.json` limits the release to the paths it lists, plus the folders of the install and uninstall steps, `.claude-plugin/`, `package.json`, `tsconfig.json`, the README, and the license, the way `npm publish` reads it. `tsconfig.json` holds the JSX settings the bundle in step 2 needs. List every folder the hooks module imports from, such as `"files": ["hooks", "src", "skills"]`, because the bundle in step 2 is built from the release.
 2. Bundles the hooks module that `hooks/hooks.json` names, with the mod's source and packages, into one readable `.js` file, writes each control character in it as a `\u` escape, and points `hooks/hooks.json` at it. Anthropic's plugin directory reads a repository without installing its packages, so it can follow a mod only when all its code is in one file.
 3. Checks the release with `claude plugin validate --strict`, and stops with the validator's message when it fails.
 4. Commits the release as the `release` branch, and builds the release archive from that commit.
 5. Builds the program `cli/` declares, and writes `SHA256SUMS` for every file of the release.
-6. Writes `.claude-plugin/marketplace.json`, listing the archive and the cmod plugin.
-7. Commits that file, tags `v<version>`, pushes the tag and the `release` branch, and creates the GitHub release.
+6. Writes `.claude-plugin/marketplace.json`, listing the archive and the cmod plugin. The cmod entry points at the `release` branch of `heyJordanParker/cmod`, so the mod's `"cmod"` dependency resolves in this marketplace and follows each cmod release with no new publish of the mod.
+7. Commits that file, tags `v<version>`, pushes the tag and the `release` branch, and creates the GitHub release. Its notes open with `## Breaking changes`, listing each `BREAKING CHANGE:` footer of a commit since the last `v` tag and the subject of each commit typed with `!`, such as `feat!: mod.claude replaces job.claude`, so the people who use the mod know what to change before they update. `--dry-run` prints that list.
 8. Prints the link to paste as the Repository when you submit the mod at [claude.ai/directory/manage](https://claude.ai/directory/manage), such as `https://github.com/owner/greeter/tree/release`. The portal reads the branch from the link, so the directory follows `release`.
 
 The release keeps `package.json`, so Claude Code still installs the mod's packages for its install and uninstall steps. It keeps `bun.lock` too, unless a `"files"` list leaves it out. `main` keeps the source only.
@@ -110,7 +113,6 @@ It needs, and refuses to start without:
 - a `package.json` with no dependency on a `file:` or `link:` path, which no user has
 - a `"files"` list, when `package.json` has one, whose every path matches a committed file
 - a `"program"` in the `cmod` key of `package.json` that names the program `cli/` declares, when `cli/` declares one
-- the network, to hash the cmod plugin release it lists, unless the mod is cmod itself
 - for a real publish, a working tree with no uncommitted changes, a `v<version>` tag that does not exist yet, a `git push` to `origin` that succeeds, and the `gh` command, which creates the GitHub release
 
 `--dry-run` builds everything into a temporary folder, and pushes nothing. It writes `marketplace.json` there too, so the working tree stays as it was. It allows uncommitted changes and an existing tag, and builds from the last commit. It prints the folder that holds the release, so you can read what the directory will read.
@@ -120,8 +122,8 @@ It needs, and refuses to start without:
 ### cmod install
 
 ```text
-cmod install <owner/repo | path> [name] [--yes]
-cmod install <name | name@marketplace> [--yes]
+cmod install <owner/repo | path> [name] [--yes] [--option key=value]...
+cmod install <name | name@marketplace> [--yes] [--option key=value]...
 ```
 
 Adds the plugin's marketplace to Claude Code and installs the plugin through Claude Code. A mod also gets the cmod plugin when Claude Code lacks it, and its install step runs. Any other plugin installs through Claude Code alone, and cmod keeps no record of it.
@@ -131,6 +133,7 @@ Adds the plugin's marketplace to Claude Code and installs the plugin through Cla
 - Given the name of a plugin Claude Code already holds, it runs a mod's install step again.
 - A path holds a `/`, such as `./my-mod`.
 - `--yes` approves the mod's install and uninstall commands without asking.
+- `--option key=value` sets one of the mod's options through `claude plugin configure`, once per option, so a scripted install needs no visit to `/config`. It refuses a key the mod does not declare, and names the keys it does ([options.md](options.md)).
 
 ### cmod update
 
@@ -172,7 +175,7 @@ Downloads a program for an install script: fetches the download for this machine
 
 ## Run by cmod
 
-cmod runs these two itself. A person runs them to see a step's whole log or to finish a step.
+cmod runs these itself. A person runs them to see a step's whole log, to finish a step, or to grant a permission.
 
 ### cmod setup
 
@@ -180,7 +183,7 @@ cmod runs these two itself. A person runs them to see a step's whole log or to f
 cmod setup <plugin-root> [--events] [--consent <sha256>] [--yes]
 ```
 
-Downloads the program the mod's `package.json` `cmod.program` names into `~/.local/bin`, runs the mod's install step, saves its uninstall step, and records the mod as set up. An unchanged mod runs nothing. `--events` prints one event per line for a program to read, and the mod's progress line in Claude Code reads them.
+Downloads the program the mod's `package.json` `cmod.program` names into `~/.local/bin`, runs the mod's install step, saves its uninstall step, grants the permissions its `cmod.permissions` lists, and records the mod as set up. A mod installed from a marketplace whose automatic updates the person has not turned on or off gets them turned on, through `"autoUpdate": true` on the marketplace's `extraKnownMarketplaces` entry in Claude Code's `settings.json`, and the consent question says so. The consent covers the scripts, the program, the keys, and the permissions together, and an update asks again only for what changed. An unchanged mod runs nothing. `--events` prints one event per line for a program to read, and the mod's progress line in Claude Code reads them.
 
 ### cmod teardown
 
@@ -188,4 +191,12 @@ Downloads the program the mod's `package.json` `cmod.program` names into `~/.loc
 cmod teardown <plugin-name> [--events]
 ```
 
-Runs a removed mod's saved uninstall step, then deletes its install record, the saved step, every version of its program, and its data folder, and forgets the scripts the person approved for it. It keeps the mod's config folder, `~/.claude/cmods/<plugin-name>`. A failed uninstall step keeps the record, so `cmod teardown` can run again.
+Runs a removed mod's saved uninstall step, then deletes its install record, the saved step, every version of its program, and its data folder, and forgets the scripts and the permissions the person approved for it. It keeps the mod's config folder, `~/.claude/cmods/<plugin-name>`. A failed uninstall step keeps the record, so `cmod teardown` can run again.
+
+### cmod permission
+
+```text
+cmod permission <mod> <name> [value] on|off
+```
+
+Turns one permission of a set-up mod on or off, such as `cmod permission ci-watch model off` or `cmod permission ci-watch network api.github.com on`. A toggle in `/mods` runs it. It refuses a permission the mod's `package.json` `cmod.permissions` does not list, and the mod sees the change before its next call, with no reload ([permissions.md](permissions.md)).

package/docs/dependencies.md

@@ -52,6 +52,14 @@ A mod that calls tracer lists it in its own `.claude-plugin/plugin.json`, and Cl
 "dependencies": ["cmod", "tracer"]
 ```
 
+A provider that changes or removes a method breaks every mod that calls it, and with automatic updates the provider can update first. Name the versions you tested with a range, and Claude Code turns your mod off with a clear error instead of letting its calls fail one by one:
+
+```json
+"dependencies": ["cmod", { "name": "tracer", "version": "^1.0" }]
+```
+
+Claude Code checks the range against the `version` in the provider's `plugin.json` when it loads your mod ([Claude Code's plugin dependencies](https://code.claude.com/docs/en/plugins/dependencies)).
+
 Claude Code then lays tracer's types file beside the mod's own types, so the call is typed:
 
 ```ts

package/docs/index.md

@@ -15,7 +15,7 @@ my-mod/
 ├── .gitignore                          node_modules/ and .claude-plugin/types/
 ├── .oxlintrc.json                      leaves .claude-plugin/types/ out of the lint
 ├── hooks/hooks.json                    names hooks/register.ts as the hooks module
-├── hooks/register.ts                   registerMod(addHook, myMod), and nothing else
+├── hooks/register.ts                   registerMod(addHook, myMod, options), and nothing else
 ├── src/mod.tsx                         defineMod: the state, the setup, the hooks, the panes
 ├── src/state.ts                        the starting state
 ├── src/panes/prompts.tsx               one definePane per file
@@ -59,7 +59,12 @@ A program the mod needs lives as source in `cli/`. `cmod publish` builds it and
 | How do I define a mod, and what can `mod` call? | [mod.md](mod.md) |
 | How does a mod watch something outside Claude Code, tell Claude about it, or ask a model? | [mod.md](mod.md#mod-every) |
 | How does a mod give Claude a prompt on a schedule, like `/loop`? | [jobs.md](jobs.md#schedule) |
-| How do I keep values across prompts, sessions, and projects? How does a person change them? | [state.md](state.md) |
+| How do I keep values across prompts, sessions, and projects? | [state.md](state.md) |
+| How does a person set a token, a URL, or a setting for my mod, for themselves or their team? | [options.md](options.md) |
+| Which hosts, programs, and files may my mod reach, and how does the person grant them? | [permissions.md](permissions.md) |
+| How does my mod find files and keep its own keys on each one, such as on a Skill? | [mod.md](mod.md#mod-metadata) |
+| How does the person finish a setup step only they can do, such as signing in? | [install-steps.md](install-steps.md#steps-in-claude-code) |
+| How do I add my mod's own page to `/mods`? | [mod.md](mod.md#mod-settings) |
 | How do I react to a Claude Code event, and what can a hook answer? | [hooks.md](hooks.md) |
 | How do I draw a pane, change a row Claude Code draws, or ask the person something? | [ui.md](ui.md) |
 | How do I add a slash command, a tool, a permission rule, a check, a prompt, a schedule, a status line, or a background program? | [jobs.md](jobs.md) |
@@ -75,10 +80,13 @@ A mod imports from the files below, and every other file in this package is inte
 | Import | Exports | Docs |
 | --- | --- | --- |
 | `mod.js` | `defineMod`, `ModDefinition`, `Mod`, `JobContext`, `Job`, `ProgressStep`, `PaneHandle`, `longestMs`, `messageOf` | [mod.md](mod.md), [jobs.md](jobs.md), [ui.md](ui.md) |
-| `mod.js` | `Claude`, `RoutedEvent`, `RoutedHook`, `ToolCalls` | [jobs.md](jobs.md) |
+| `mod.js` | `Claude`, `ModClaude`, `RoutedEvent`, `RoutedHook`, `ToolCalls` | [jobs.md](jobs.md) |
+| `mod.js` | `FileMatch`, `Metadata`, `ScrollArgs` | [mod.md](mod.md), [ui.md](ui.md) |
+| `installer.js` | `defineStep`, `Step` | [install-steps.md](install-steps.md#steps-in-claude-code) |
 | `mod.js` | `ModEvent`, `ModHook`, `HookOptions`, `HookInput`, `HookAnswer` | [hooks.md](hooks.md) |
 | `mod.js` | `notInstalled` | [dependencies.md](dependencies.md) |
-| `register.js` | `registerMod`, `registerPermissionCheck` | [mod.md](mod.md) |
+| `register.js` | `registerMod`, `registerPermissionCheck`, `registeredMod` | [mod.md](mod.md) |
+| `options.js` | `option`, `Option`, `Options`, `OptionValues`, `OptionValue`, `OptionKind`, `UserConfigField`, `userConfigOf` | [options.md](options.md) |
 | `shell.js` | `parseShell`, `ParsedShell`, `ShellCommand` | [hooks.md](hooks.md) |
 | `path.js` | `resolve`, `join`, `dirname`, `basename`, `extname`, `relative`, `isAbsolute`, `normalize` | [hooks.md](hooks.md) |
 | `testing.js` | `testMod`, `TestOptions`, `TestInput`, `TestedMod`, `Fakes`, `Shown`, `TestCall` | [testing.md](testing.md) |

package/docs/install-steps.md

@@ -34,16 +34,48 @@ cmod refuses a `cmod` key that breaks these rules, with the fix in the message:
 
 ## Consent
 
-Before a step runs for the first time, cmod shows the person the commands and the keys, and asks to run them. cmod hashes the commands, the keys, and every file in each script folder, and remembers the hash the person approved. A change to any of those asks again.
+Before a step runs for the first time, cmod shows the person the commands, the keys, and the permissions, and asks to run them. cmod hashes the commands, the keys, the permissions, and every file in each script folder, and remembers the hash the person approved with each permission. A change to any of those asks again, and an added permission is the only one it asks about ([permissions.md](permissions.md)).
 
-- In Claude Code, the mod asks `<mod> runs <install> to install, runs <uninstall> when you remove it and binds shift+tab to /mode. Install it now?` with `Install` and `Not now`, naming only what the mod has. A progress line above the prompt shows the install.
+- In Claude Code, the mod opens the installer pane, `Install <mod>`, focused. It lists `<mod> wants to:`, each permission as one sentence, then `and change your computer:` with `Run <install> now, and <uninstall> when you remove it` and `Bind shift+tab to /mode`, naming only what the mod has. `Accept` (a) runs the setup, and a progress line above the prompt shows the install. `Not now` (n) and Escape decline.
 - In a session with no screen, such as `claude -p`, the mod waits and logs `<mod> waits for consent to run <install>. Run cmod install <mod> in a terminal.`
-- In a terminal, `cmod install`, `cmod link`, `cmod try`, and `cmod update` print the commands, the program, and the keys, and ask `Set up <mod>? [y/N]`. `--yes` approves without asking.
+- In a terminal, `cmod install`, `cmod link`, `cmod try`, and `cmod update` print the commands, the program, the keys, and the permissions, and ask `Set up <mod>? [y/N]`. `--yes` approves without asking.
 - `Not now` leaves the mod off and logs `<mod> is not installed. Run cmod install <mod> to install it.`
 
 The mod starts only once its install step has run ([mod.md](mod.md)).
 
-In Claude Code, the mod sets itself up through the `cmod` that PATH finds, and only through one that knows every step it has. A mod with `keys` waits for cmod 0.1.12 or later, because an older cmod skips the keys. While PATH finds an older one, the line above the prompt says `PATH finds cmod <version>, and <mod> needs cmod 0.1.12 or later. Run npm i -g @cmodjs/cli, or put ~/.local/bin ahead of the old cmod on PATH.` The mod sets up as soon as a new enough cmod answers, such as the one the cmod plugin installs into `~/.local/bin` at its first start.
+## Automatic updates
+
+Claude Code updates a plugin by itself only when its marketplace has automatic updates on, and they are off for every marketplace that is not Anthropic's. So the setup of a mod installed from a marketplace turns them on, through `"autoUpdate": true` on that marketplace's `extraKnownMarketplaces` entry in `settings.json`. The consent lists it as `Update <mod> automatically from the <marketplace> marketplace`, and a mod with nothing to consent to logs it. The setup never changes a choice the person made, in `settings.json` or with the toggle under `/plugin` Marketplaces, and leaves a linked mod alone.
+
+Claude Code downloads an update in the background and loads it at the next launch or `/reload-plugins`. An update whose scripts, keys, or permissions changed waits for consent again, so an update never runs a new install step unasked.
+
+In Claude Code, the mod sets itself up through the `cmod` that PATH finds, and only through one that knows every step it has. A mod with `keys` waits for cmod 0.1.12 or later, because an older cmod skips the keys, and a mod with `permissions` waits for cmod 0.2.0 or later, because an older cmod grants none of them. While PATH finds an older one, the line above the prompt says `PATH finds cmod <version>, and <mod> needs cmod 0.1.12 or later. Run npm i -g @cmodjs/cli, or put ~/.local/bin ahead of the old cmod on PATH.` The mod sets up as soon as a new enough cmod answers, such as the one the cmod plugin installs into `~/.local/bin` at its first start.
+
+## Steps in Claude Code
+
+Some setup only the person can do, such as signing in to a service. A mod lists those steps in `installer`, and the installer pane shows each one after the permissions and the options, once the mod has started:
+
+```ts
+import { defineStep } from '../node_modules/@cmodjs/core/installer.js'
+
+const signIn = defineStep({
+  id: 'sign-in',
+  title: 'Sign in to GitHub',
+  render: () => <Text>Run gh auth login in a terminal, then press Next.</Text>,
+  isDone: async (mod) => (await mod.process.run(['gh', 'auth', 'status'])).exitCode === 0,
+})
+
+export const ciWatch = defineMod({ name: 'ci-watch', installer: [signIn], setup(mod) { … } })
+```
+
+```ts
+defineStep<State>(step: { id: string; title: string; render(mod, props): RenderElement; isDone(mod): boolean | Promise<boolean> }): Step<State>
+```
+
+- `id` is 1 to 64 letters, digits, `_`, or `-`. `title` is the line above the step, with `(1 of 2)`. `defineStep` throws for either one missing.
+- `render` draws the step's body, the way a pane's `render` does ([ui.md](ui.md)).
+- `isDone` says whether the step is finished. A step that is done is skipped, so the pane opens only for what is left. `Next` checks `isDone`, and shows `Finish <title> first.` while it is false. The last step's button says `Finish`.
+- `Not now` closes the pane and logs `<mod> needs one more step, starting with <title>. Run /mods <mod> to finish.` The mod keeps running. `/mods <mod>` shows `Needs setup: <title>` with a `Finish setup` button, which opens the pane on the first step left.
 
 ## Key bindings
 

package/docs/jobs.md

@@ -167,6 +167,8 @@ A `command` pattern is not a glob. cmod splits it into words the way it splits a
 
 ## permissions
 
+A `deny` rule needs no permission. An `ask` rule takes effect only with `"approve": true` in `package.json` `"cmod".permissions` ([permissions.md](permissions.md)).
+
 ```ts
 permissions<State>(rules: PermissionRules<State> | ((state: State) => PermissionRules<State>)): Job<void, State>
 
@@ -222,6 +224,8 @@ export const guard = defineMod({
 
 ## check
 
+Its command needs `"run"` with the program's name, such as `"run": ["tsc"]` ([permissions.md](permissions.md)).
+
 ```ts
 check<State>(options: { readonly after: Target | Target[]; readonly run: readonly string[]; readonly timeoutMs?: number }): Job<void, State>
 ```
@@ -247,6 +251,8 @@ export const lint = defineMod({
 
 ## prompt
 
+It needs `"prompt": true`. Without the grant it adds nothing and logs once which line to add ([permissions.md](permissions.md)).
+
 ```ts
 prompt<State>(options: {
   name: string
@@ -288,6 +294,8 @@ export const conventions = defineMod({
 
 ## schedule
 
+It needs `"prompt": true`, because each cron starts a turn ([permissions.md](permissions.md)).
+
 ```ts
 schedule<State>(entry: Schedule | ((state: State) => Schedule | undefined)): Job<void, State>
 
@@ -346,6 +354,8 @@ export const usage = defineMod({
 
 ## program
 
+It needs `"run"` with the program's name. Without the grant the program stops at once and names the line to add ([permissions.md](permissions.md)).
+
 ```ts
 program(options: { readonly command: readonly string[]; readonly environment?: Record<string, string> }): Job<Program>
 
@@ -394,17 +404,20 @@ A `Job` is a function. `mod.use` calls it with a `JobContext` and returns what i
 ```ts
 type JobContext<State> = {
   readonly mod: Mod<State>
-  readonly claude: Claude
-  on<N extends RoutedEvent>(event: N, hook: RoutedHook<N>): void
   announce(feature: string): void
   reserveName(kind: string, name: string, taken: string): void
   readonly toolCalls: ToolCalls
 }
 ```
 
-- `claude` reaches Claude Code itself. [The claude members](#the-claude-members) lists each one.
-- `claude.store` is where cmod saves `mod.state`, under keys that start with `<mod>.`, such as `<mod>.<key>`. A job of your own never writes those keys, or it changes the mod's state behind cmod's back.
-- `on` adds a Claude Code hook-module handler, `(e, next) => …`, on a `classic.<ModEvent>` event or on `tool.check`, `tool.call`, `prompt.submit`, `prompt.context`, `command.run`, `session.measure`, `skill.prompt`, `ui.render`, `ui.press`, `ui.scroll`, `ui.close`, or `cmod.call`. The handler calls `next(e)` to pass the event on. A job with a handler on `tool.check` or `classic.PermissionRequest` needs `registerPermissionCheck` in `hooks/register.ts` ([mod.md](mod.md)).
+A job reaches Claude Code through `mod.claude`, the same member every hook has:
+
+- `mod.claude` holds Claude Code's own calls. [The claude members](#the-claude-members) lists each one. Each call checks the permission it needs, as `mod`'s own members do ([permissions.md](permissions.md)).
+- `mod.claude.store` is where cmod saves `mod.state`, under keys that start with `<mod>.`, such as `<mod>.<key>`. A job of your own never writes those keys, or it changes the mod's state behind cmod's back.
+- `mod.claude.on` adds a Claude Code hook-module handler, `(e, next) => …`, on a `classic.<ModEvent>` event or on `tool.check`, `tool.call`, `prompt.submit`, `prompt.context`, `command.run`, `session.measure`, `skill.prompt`, `ui.render`, `ui.press`, `ui.scroll`, `ui.close`, or `cmod.call`. The handler calls `next(e)` to pass the event on. cmod checks what it answers against the person's grants, part by part ([permissions.md](permissions.md#when-a-hook-answer-has-no-grant)). A job with a handler on `tool.check` or `classic.PermissionRequest` needs `registerPermissionCheck` in `hooks/register.ts` ([mod.md](mod.md)).
+
+The context adds what only a job needs:
+
 - `announce` adds a phrase to the list cmod logs when the mod first starts.
 - `reserveName` throws `taken` when the mod already reserved that `kind` and `name`. A job calls it to refuse a duplicate.
 - `toolCalls.agentOf(toolUseId)` resolves `{ agentId?, agentType? }`, the subagent behind a call.
@@ -413,9 +426,9 @@ type JobContext<State> = {
 ```ts
 import { defineMod, type Job } from '../node_modules/@cmodjs/core/mod.js'
 
-const clock: Job<{ now(): Promise<number> }> = ({ claude, announce }) => {
+const clock: Job<{ now(): Promise<number> }> = ({ mod, announce }) => {
   announce('a clock')
-  return { now: () => claude.clock.now() }
+  return { now: () => mod.claude.clock.now() }
 }
 
 export const timer = defineMod({
@@ -433,7 +446,9 @@ export const timer = defineMod({
 
 `mod.js` exports the types `Claude`, `RoutedEvent`, `RoutedHook`, and `ToolCalls`, so a job of your own names them in its own helpers, such as `(claude: Claude, calls: ToolCalls): RoutedHook<'command.run'> => …`.
 
-Each member calls the member of the same name in Claude Code's hooks API, `$`, with the same arguments. The `env` members read `$.env.get` instead.
+Each member calls the member of the same name in Claude Code's hooks API, `$`, with the same arguments. The `env` members read `$.env.get` instead. `mod.claude.on` adds a handler, as [Write a job of your own](#write-a-job-of-your-own) shows.
+
+A member that does what a permission covers checks it first and rejects with the fix: `process` needs `run`, `http.fetch` needs `network`, `fs.write` outside the project and the data folder needs `files` or, for Claude Code's own settings files, `config`, `fs.read` of a transcript needs `conversation`, `session.messages` needs `conversation`, `session.append` and `prompt.submit` need `prompt`, `model.complete` needs `model`, `agent.spawn` needs `agents`, `config.set` needs `config`, and `tool.call` needs `tools`, except `CronCreate`, which needs `prompt`, and `CronList` and `CronDelete`, which need nothing ([permissions.md](permissions.md)).
 
 | Member | What it does |
 | --- | --- |
@@ -454,7 +469,8 @@ Each member calls the member of the same name in Claude Code's hooks API, `$`, w
 | `process.spawn(request)` | Starts a program and streams its output. `mod.process.spawn` is built on it. |
 | `fs.read`, `fs.write`, `fs.list`, `fs.exists`, `fs.stat` | What `mod.fs` calls. A relative path is under the session's working folder. |
 | `http.fetch(url, init?)` | What `mod.http.fetch` calls. |
-| `settings.read(args?)` | What `mod.settings.read` calls. |
+| `settings.read(args?)` | Reads Claude Code's own `settings.json` files. Without `{ source }` it answers every source merged. `user`, `project`, `local`, `flag`, and `policy` each answer one. |
+| `config.list()`, `config.set({ key, value })` | Lists the rows `/config` shows, and changes one, such as `<mod>.<option>`. `set` needs `config`. |
 | `store.get`, `store.set`, `store.delete`, `store.keys` | The plugin's key-value store, where cmod also keeps `mod.state`. |
 | `clock.now()` | Resolves milliseconds since the epoch. |
 | `clock.after(ms, fn)` | Calls `fn` once after `ms` milliseconds, and returns `{ cancel() }`. |