@cmodjs/core 0.1.14 → 0.2.1

package/docs/mod.md

@@ -5,21 +5,25 @@
 ## defineMod
 
 ```ts
-defineMod<State, Name>(definition: ModDefinition<State, Name>): ModDefinition<State, Name>
+defineMod<State, Name, Options>(definition: ModDefinition<State, Name, Options>): ModDefinition<State, Name, Options>
 ```
 
 ```ts
-type ModDefinition<State, Name> = {
+type ModDefinition<State, Name, Options> = {
   readonly name: Name
   readonly state?: State
+  readonly options?: Options
   readonly api?: { … }
-  setup(mod: Mod<State>): void | Promise<void>
+  readonly installer?: readonly Step<State>[]
+  setup(mod: Mod<State, Options>): void | Promise<void>
 }
 ```
 
-- `name` is the mod's name. Use the `name` in `.claude-plugin/plugin.json`. Claude Mod Manager (cmod) keys the saved state and the `state.json` files by this name, and the data folder and the Skill overrides by the plugin's name, so the two must match. `defineMod` throws `defineMod: the mod needs a name, such as the name in .claude-plugin/plugin.json.` for a blank name.
+- `name` is the mod's name. Use the `name` in `.claude-plugin/plugin.json`. Claude Mod Manager (cmod) keys the saved state and the options by this name, and the data folder and the Skill overrides by the plugin's name, so the two must match. `defineMod` throws `defineMod: the mod needs a name, such as the name in .claude-plugin/plugin.json.` for a blank name.
 - `state` holds the starting values, grouped by how long they last. [state.md](state.md) explains the groups.
+- `options` declares what a person sets, such as a token, and types `mod.options`. [options.md](options.md) explains them.
 - `api` holds the methods other mods call. [dependencies.md](dependencies.md) explains it.
+- `installer` lists the steps the person finishes in Claude Code after the permissions and the options, such as signing in. [install-steps.md](install-steps.md#steps-in-claude-code) explains them.
 - `setup` runs once when the mod starts. It adds hooks, panes, slot renders, and jobs. It may be `async`.
 
 ```tsx
@@ -41,14 +45,15 @@ export const greeter = defineMod({
 
 ## When setup runs
 
-Claude Code loads the mod at the start of each session. cmod then checks that the mod is set up. A mod with an install step that has not run waits for the person's consent and the install first ([install-steps.md](install-steps.md)). Then cmod loads the saved state, runs `setup`, and marks as open each of the mod's panes that Claude Code already shows.
+Claude Code loads the mod at the start of each session. cmod then checks that the mod is set up. A mod the person has not accepted yet opens the installer pane, `Install <name>`, which lists its permissions and the changes it makes to the computer, and waits for Accept ([install-steps.md](install-steps.md)). An option with no default and no value is asked on the next page of the same pane. Then cmod loads the saved state, runs `setup`, marks as open each of the mod's panes that Claude Code already shows, and opens the pane again for each `installer` step the mod declares that is not done.
 
 The first time a version starts, cmod shows the toast `<name> is ready` and logs `<name> added <what setup added>`, such as `the my-mod pane, a render of AbovePrompt and a hook on UserPromptSubmit`.
 
 When a step fails, the mod does not start. Its progress line above the prompt names the failure and the fix:
 
 - `<mod>: state.<group> is not a lifetime. …` or `<mod>: state.<group> is not an object of values. …` when the declared state is not valid ([state.md](state.md)).
-- `its state did not load: <error>` when reading the saved values or a `state.json` fails.
+- `its state did not load: <error>` when reading the saved values fails.
+- `it needs <titles>` when the person chose Not now on an option with no default, or no one can answer, as in `claude -p` ([options.md](options.md)). This one says `Set it in /config.` instead, and Claude Code reloads the mod once the value is set.
 - `its setup function threw: <error>` when `setup` throws or rejects.
 - `its open panes did not load: <error>` when Claude Code cannot list the open panes.
 - `it decides permissions on <events>, so hooks/register.ts must call registerPermissionCheck(addHook) after registerMod` when `setup` adds a hook on `PermissionRequest`, or a job that decides permissions, and `register.ts` does not register the permission check.
@@ -60,43 +65,45 @@ Each of these says `Fix it, then run /reload-plugins.`
 `hooks/hooks.json` names `hooks/register.ts` as the plugin's hooks module. `register.ts` calls `registerMod` and does nothing else:
 
 ```ts
-import type { On } from 'claude-code'
+import type { On, PluginOptions } from 'claude-code'
 import { registerMod } from '../node_modules/@cmodjs/core/register.js'
 import { greeter } from '../src/mod.js'
 
-export function register(addHook: On): void {
-  registerMod(addHook, greeter)
+export function register(addHook: On, options: PluginOptions): void {
+  registerMod(addHook, greeter, options)
 }
 ```
 
 ```ts
-registerMod<State>(addHook: On, definition: ModDefinition<State>): void
+registerMod<State, Options>(addHook: On, definition: ModDefinition<State, string, Options>, options: PluginOptions): void
 registerPermissionCheck(addHook: On): void
+registeredMod(): ModDefinition | undefined
 ```
 
-`registerMod` registers one handler per Claude Code event the mod can use, and routes each event to the mod. A `PreToolUse` hook runs on `tool.call`, which `registerMod` registers ([hooks.md](hooks.md)). It leaves out Claude Code's permission check, the events `tool.check` and `PermissionRequest`.
+`registerMod` registers one handler per Claude Code event the mod can use, and routes each event to the mod. `options` is what Claude Code passes `register`: the values of the mod's options ([options.md](options.md)). `registeredMod` returns the definition `registerMod` got, for `cmod check` to read the mod's options without starting it. A `PreToolUse` hook runs on `tool.call`, which `registerMod` registers ([hooks.md](hooks.md)). It leaves out Claude Code's permission check, the events `tool.check` and `PermissionRequest`.
 
 A mod that decides permissions calls `registerPermissionCheck` after `registerMod`. That covers a `PreToolUse` hook that answers `permissionDecision: 'allow'` or `'ask'`, a hook on `PermissionRequest`, the `permissions` job, and a job of your own on `tool.check`:
 
 ```ts
-export function register(addHook: On): void {
-  registerMod(addHook, guard)
+export function register(addHook: On, options: PluginOptions): void {
+  registerMod(addHook, guard, options)
   registerPermissionCheck(addHook)
 }
 ```
 
-A mod without it has no part in Claude Code's permission check, so the plugin directory reads it as one that never answers a permission. A mod that decides permissions without it does not start, and its progress line names the line to add.
+Such a mod also declares `"approve": true` in its `package.json` `"cmod".permissions`, so the person grants it at install. `cmod check` adds the line when it is missing, and without the grant cmod drops every allow or ask the mod answers, so Claude Code decides those calls itself ([permissions.md](permissions.md)). A mod without `registerPermissionCheck` has no part in Claude Code's permission check, so the plugin directory reads it as one that never answers a permission. A mod that decides permissions without it does not start, and its progress line names the line to add.
 
 Keep `register.ts` this small. Claude Code checks a hooks module before it loads it, and refuses some shapes, such as a `$` passed to a function in another module. The plugin directory reads the bundled module too, and flags it when the name of `register`'s first parameter is declared anywhere else in the bundle. `@cmodjs/core` declares `on` as the method `mod.on`, so name that parameter `addHook`. Declare `register` as a function, as here: `cmod publish` bundles the hooks module into one file, and Claude Code refuses a bundled `register` that is not one.
 
 ## What `mod` can call
 
-`setup` gets `mod`, of type `Mod<State>`. Every hook, render, and job gets the same `mod`.
+`setup` gets `mod`, of type `Mod<State, Options>`. Every hook, render, and job gets the same `mod`.
 
 ```ts
-type Mod<State> = {
+type Mod<State, Options> = {
   readonly name: string
   readonly state: Readonly<State>
+  readonly options: OptionValues<Options>
   readonly dataFolder: string
   readonly projectRoot: string
   readonly cwd: string
@@ -105,13 +112,16 @@ type Mod<State> = {
   every(ms, hook): Timer
   readonly ui: { pane, render, toast, progress, ask, scroll }
   readonly process: { run, spawn }
-  readonly fs: { read, write, list, exists, stat }
+  readonly fs: { read, write, list, exists, stat, find }
+  readonly metadata: { read, update }
   readonly http: { fetch }
-  readonly settings: { read }
+  readonly settings: { page, open }
   readonly session: { messages, append, submit }
   readonly agent: { spawn }
   readonly model: { complete }
+  readonly permissions: { has }
   readonly dependencies: CmodDependencies
+  readonly claude: ModClaude
 }
 ```
 
@@ -119,6 +129,7 @@ type Mod<State> = {
 | --- | --- | --- |
 | `name` | The mod's name from `defineMod`. | |
 | `state` | The mod's values. Assign to a key to change it. | [state.md](state.md) |
+| `options` | The values a person set for the mod's options, typed from their declaration. Read-only. | [options.md](options.md) |
 | `dataFolder` | The mod's own folder in the cmod store: `$XDG_DATA_HOME/cmod/data/<plugin name>`, or `~/.local/share/cmod/data/<plugin name>` when `XDG_DATA_HOME` is not set. The install step gets the same folder as `CMOD_DATA`. cmod deletes it when the mod is removed. | [install-steps.md](install-steps.md) |
 | `projectRoot` | The project the session works in. It follows `/cd`. | |
 | `cwd` | The session's working folder. It follows a `cd` in a Bash or PowerShell call, and `/cd`. | |
@@ -127,13 +138,16 @@ type Mod<State> = {
 | `every` | Runs a function every so many milliseconds while the session runs. | below |
 | `ui` | Panes, slot renders, toasts, progress lines, questions, and scrolling. | [ui.md](ui.md) |
 | `process` | Runs a program. | below |
-| `fs` | Reads, writes, and looks up files. | below |
+| `fs` | Reads, writes, looks up, and finds files. | below |
+| `metadata` | Reads and changes the mod's keys in one file's metadata. | below |
 | `http` | Fetches a URL. | below |
-| `settings` | Reads Claude Code's settings. | below |
+| `settings` | Adds the mod's own pages to `/mods`, and opens them. | below |
 | `session` | Reads the conversation or a subagent's, adds a note Claude reads, and asks Claude for a turn. | below |
 | `agent` | Starts a subagent. | below |
 | `model` | Asks a model one question, outside the conversation. | below |
+| `permissions` | Says whether the person has a permission turned on. `process`, `fs.write`, `metadata.update`, `http`, `session`, `agent`, `model`, and `claude` each check theirs. | [permissions.md](permissions.md) |
 | `dependencies` | Calls the methods of other mods. | [dependencies.md](dependencies.md) |
+| `claude` | Claude Code's own calls and events, for what `mod` has no member for. | [jobs.md](jobs.md#the-claude-members) |
 
 ### mod.every
 
@@ -195,6 +209,7 @@ mod.fs.write(path: string, text: string): Promise<void>
 mod.fs.list(path?: string): Promise<FsEntry[]>
 mod.fs.exists(path: string): Promise<boolean>
 mod.fs.stat(path: string, options?: { resolve: boolean }): Promise<FsStat>
+mod.fs.find(glob: string | readonly string[]): Promise<readonly FileMatch[]>
 ```
 
 - A relative path is under the session's working folder. An absolute path is used as given. Text is UTF-8.
@@ -204,7 +219,64 @@ mod.fs.stat(path: string, options?: { resolve: boolean }): Promise<FsStat>
 - `exists` answers whether the path leads to a file or a folder.
 - `stat` answers `{ kind, size, mtimeMs, isLink }` of what the path leads to, following a symbolic link, and rejects a missing path. With `{ resolve: true }` it also answers `realPath`: the absolute path, every symbolic link followed.
 
-A file the mod ships is under the plugin's folder. `mod` has no member that names that folder, so a job of your own reads it from `claude.plugin.root` ([jobs.md](jobs.md#the-claude-members)). A file the mod keeps for itself belongs in `mod.dataFolder`.
+A file the mod ships is under the plugin's folder, `mod.claude.plugin.root` ([jobs.md](jobs.md#the-claude-members)). A file the mod keeps for itself belongs in `mod.dataFolder`.
+
+`find` answers every file a glob matches, each with its metadata, so a mod finds the Skills, agents, scripts, or notes it acts on in one call:
+
+```ts
+type FileMatch = { readonly path: string; readonly name?: string; readonly metadata: Readonly<Record<string, string>>; readonly error?: string }
+```
+
+- A glob starting with `~/.claude` starts at Claude Code's config folder, `CLAUDE_CONFIG_DIR` when it is set. One starting with `~/` starts at home, one starting with `/` is absolute, and any other starts at the project root. Several globs answer each file once.
+- `path` is absolute. `name` is a Markdown file's frontmatter `name`. `metadata` holds the mod's own keys, bare, as `mod.metadata.read` answers them.
+- `find` follows symbolic links into the folders they point at, once each. It skips `.git` and `node_modules` unless the glob names them.
+- A file whose metadata cmod cannot read comes back with empty `metadata` and an `error` naming the line, and cmod logs it once.
+- cmod keeps what it read of each file until the file's modified time or size changes.
+
+```ts
+const skills = await mod.fs.find(['~/.claude/skills/*/SKILL.md', '.claude/skills/*/SKILL.md'])
+const planning = skills.filter((skill) => skill.metadata['modes']?.split(' ').includes('plan'))
+```
+
+### mod.metadata
+
+```ts
+mod.metadata.read(path: string): Promise<Readonly<Record<string, string>>>
+mod.metadata.update(path: string, change: (metadata: Record<string, string>) => void): Promise<void>
+```
+
+Metadata is a file's own set of string keys, kept in the file, so it moves and is committed with the file. Each mod reads and writes its own keys only: the file stores them as `<mod>.<key>`, and the mod sees them bare. A value is one line of text, and a list is one space-separated string.
+
+Where a file keeps its metadata depends on its kind:
+
+```markdown
+---
+name: plan
+metadata:
+  modes.modes: plan build
+---
+```
+
+```sh
+#!/bin/sh
+# /// metadata
+# modes.modes: plan build
+# ///
+```
+
+- A Markdown file keeps it in its frontmatter, under `metadata:`.
+- A `.sh`, `.py`, `.ts`, `.js`, `.yaml`, or `.toml` file keeps it in a `/// metadata` comment block after any shebang, in the file's own comment, `#` or `//`, the way PEP 723 keeps a Python script's dependencies.
+- Any other file keeps it in a sidecar, `<file>.meta`.
+
+`update` hands `change` the mod's current keys, and writes what `change` leaves. It changes only the metadata block, keeps other mods' keys, writes nothing when nothing changed, and removes an empty block. It writes through a symbolic link to the file it points at. Writing a file outside the project and the mod's data folder needs the `files` permission, as `mod.fs.write` does ([permissions.md](permissions.md)). A key is letters, digits, `_`, `.`, and `-`, and `update` rejects any other key and a value with a line break.
+
+```ts
+await mod.metadata.update('.claude/skills/plan/SKILL.md', (metadata) => {
+  metadata['modes'] = 'plan build'
+})
+```
+
+`cmod check` reads the metadata of every file the mod ships, and fails one cmod cannot read.
 
 ### mod.http
 
@@ -218,35 +290,29 @@ mod.http.fetch(url: string, init?: HttpInit): Promise<HttpResponse>
 ### mod.settings
 
 ```ts
-mod.settings.read(args?: { source?: 'user' | 'project' | 'local' | 'flag' | 'policy' }): Promise<Settings>
+mod.settings.page(page: Pane<State>): void
+mod.settings.open(pageId?: string): Promise<void>
 ```
 
-Without a `source` it answers the settings Claude Code runs under, every source merged. With a `source` it answers that one source: `user` is `~/.claude/settings.json`, `project` is `.claude/settings.json`, and `local` is `.claude/settings.local.json`. The answer is keyed as a `settings.json` is, such as `permissions`, `env`, and `enabledPlugins`.
+`/mods` shows each mod's options, permissions, and keys. `page` adds a page of the mod's own to its entry there, drawn as any pane is ([ui.md](ui.md)). `open` opens that page, or with no id opens the mod's entry in `/mods`. `open` rejects for an id `page` did not add.
 
-```ts
-import { defineMod } from '../node_modules/@cmodjs/core/mod.js'
-
-export const pluginCount = defineMod({
-  name: 'plugin-count',
-  setup(mod) {
-    mod.on('SessionStart', async () => {
-      const enabled = (await mod.settings.read({ source: 'user' }))['enabledPlugins'] as Record<string, unknown> | undefined
-      mod.ui.toast(`${Object.keys(enabled ?? {}).length} plugins are enabled`)
-    })
-  },
-})
+```tsx
+mod.settings.page(definePane({ id: 'runs', title: 'Runs', render: (current) => <Text>{current.state.session.lastRun}</Text> }))
+mod.use(slashCommand({ name: 'ci-runs', description: 'Show the CI runs', reply: () => void mod.settings.open('runs') }))
 ```
 
+Claude Code's own `settings.json` files are read with `mod.claude.settings.read`, such as `(await mod.claude.settings.read({ source: 'user' }))['enabledPlugins']` ([jobs.md](jobs.md#the-claude-members)).
+
 ### mod.session
 
 ```ts
 mod.session.messages(): Promise<SessionMessage[]>
-mod.session.messages(args: { agentId?: string; as?: 'api' }): Promise<…>
+mod.session.messages(args: { agentId: string }): Promise<SessionMessage[] | { deny: string }>
 mod.session.append(text: string): Promise<void>
 mod.session.submit(text: string): Promise<void>
 ```
 
-`messages` reads the main conversation, one `{ role, text, toolUses, toolResults }` entry per message. A message has no id of its own, and each tool use carries its `tool_use_id`. `{ agentId }` reads that subagent's conversation instead, the id a `SubagentStart` or `SubagentStop` hook gets as `agent_id`, and answers `{ deny }` when the session cannot read it, so `Array.isArray` tells the two apart. `{ as: 'api' }` reads it in the Messages API form, `{ role, content }` with the content blocks whole.
+`messages` reads the main conversation, one `{ role, text, toolUses, toolResults }` entry per message. A message has no id of its own, and each tool use carries its `tool_use_id`. `{ agentId }` reads that subagent's conversation instead, the id a `SubagentStart` or `SubagentStop` hook gets as `agent_id`, and answers `{ deny }` when the session cannot read it, so `Array.isArray` tells the two apart. The Messages API form, `{ role, content }` with the content blocks whole, is `mod.claude.session.messages({ as: 'api' })`.
 
 ```ts
 mod.on('SubagentStop', async ({ agent_id }) => {

package/docs/options.md

@@ -0,0 +1,93 @@
+# Options
+
+An option is a value a person sets for a mod and the mod reads, such as a token, a URL, or how often to check. The mod declares its options in `defineMod`, and `mod.options` holds their values, typed from the declaration. Claude Code stores them: it shows each one in `/config`, keeps a secret in the system keychain, and reloads the mod when one changes.
+
+`mod.state` is the other kind of value: what the mod owns and changes as it runs ([state.md](state.md)).
+
+## Declare the options
+
+```ts
+import { defineMod } from '../node_modules/@cmodjs/core/mod.js'
+import { option } from '../node_modules/@cmodjs/core/options.js'
+
+export const ciWatch = defineMod({
+  name: 'ci-watch',
+  options: {
+    githubToken: option.secret({ title: 'GitHub token', description: 'Reads your CI runs' }),
+    every: option.number({ title: 'Check every', description: 'Minutes between checks', default: 10, min: 1 }),
+    branch: option.text({ title: 'Branch', description: 'The branch to watch', default: 'main' }),
+  },
+  setup(mod) {
+    mod.ui.toast(`Watching ${mod.options.branch} every ${mod.options.every} minutes`)
+  },
+})
+```
+
+`mod.options.every` is a `number` and `mod.options.branch` a `string`, so `tsc` catches a typo or a wrong type.
+
+| Helper | The value | Claude Code shows it as |
+| --- | --- | --- |
+| `option.text({ title, description, default? })` | `string` | a text field |
+| `option.secret({ title, description })` | `string` | a masked field, kept in the keychain |
+| `option.number({ title, description, default?, min?, max? })` | `number` | a number field |
+| `option.toggle({ title, description, default? })` | `boolean`, `false` unless `default` says otherwise | a toggle |
+| `option.choice(choices, { title, description, default? })` | one of `choices` | a picker |
+| `option.folder({ title, description, default? })` | `string`, a folder path | a folder field |
+| `option.file({ title, description, default? })` | `string`, a file path | a file field |
+| `option.list({ title, description, default? })` | `readonly string[]` | a list of text |
+
+- An option name is letters, digits, and `_`, starting with a letter, because Claude Code passes each option on as `CLAUDE_PLUGIN_OPTION_<NAME>`. `defineMod` throws for another name.
+- `title` is the label `/config` shows. `description` is the help text under it.
+- A secret has no default, so a token never ships in the mod.
+
+## Where the values come from
+
+Each value is, in order of precedence:
+
+1. A value the person's organization set in managed settings. `/config` shows it locked.
+2. The value in the project's `options.json`.
+3. The value the person set in `/config`.
+4. The `default` in the declaration.
+
+An option with no default and no value is asked before `setup` runs, on a page of the installer pane: one field per option, each saved to `/config` as the person submits it. A secret is set in `/config` itself, where Claude Code keeps it in the keychain, and the page says so. When the person chooses Not now, or no one can answer, as in `claude -p`, the mod does not start: its progress line says `it needs <title>` and `Set it in /config.`, and Claude Code reloads the mod once the value is set.
+
+`cmod install`, `cmod link`, and `cmod try` set options from the terminal with `--option key=value`, once per option ([commands.md](commands.md)).
+
+`mod.options` follows the values while the session runs. Read an option where you use it, as in `mod.options.branch`, so a change applies at once. A change in `/config` reloads the mod, and a `/cd` reads the new project's `options.json`.
+
+## Set options for a team
+
+A project sets options for everyone who works in it with an `options.json` in its config folder, committed with the repository:
+
+```text
+<project>/.claude/cmods/<mod>/options.json
+```
+
+```json
+{ "branch": "release", "every": 5 }
+```
+
+cmod ignores each entry it cannot use and logs one line naming the file, the entry, and the fix:
+
+- a file that is not JSON, or not a JSON object
+- an option the mod does not declare
+- a secret, because the file is committed for everyone to read
+- a value the option does not take, such as `0` for an option with `min: 1`
+
+## plugin.json userConfig
+
+Claude Code reads a plugin's options from `userConfig` in `.claude-plugin/plugin.json` before it loads the mod. `cmod check` writes `userConfig` from the options `defineMod` declares, so the declaration is the one place to change them. `cmod publish` refuses a `plugin.json` whose `userConfig` differs: run `cmod check`, then commit `.claude-plugin/plugin.json`.
+
+`cmod check` never writes `required`, because Claude Code refuses to load a mod while a required option has no value. cmod asks for an option with no default instead.
+
+`userConfigOf(options)`, exported from `options.js`, returns the `userConfig` for a declaration.
+
+## Test options
+
+`testMod(mod, { options: { githubToken: 'ghp_test' } })` starts the tested mod with those values, as Claude Code passes them. Each option left out gets its default. A test that leaves out an option with no default fails with `<mod> needs <title>, which a person sets in /config. Give it to the tested mod: testMod(mod, { options: { <key>: … } }).` `fakes.config.list` answers the `/config` rows, so a test can lock a value as managed settings do ([testing.md](testing.md)).
+
+```ts
+const tested = testMod(ciWatch, { options: { githubToken: 'ghp_test', branch: 'develop' } })
+await tested.start()
+expect(tested.shown.toasts).toContain('Watching develop every 10 minutes')
+```

package/docs/permissions.md

@@ -0,0 +1,88 @@
+# Permissions
+
+A mod declares what it does beyond drawing and answering hooks: the hosts it connects to, the programs it runs, the files it changes outside its project, and whether it reads the conversation, adds text Claude reads, asks a model, starts agents, uses Claude's tools, changes Claude Code's settings, or approves tool calls. The person sees each permission as one sentence when they install the mod, turns each one on or off in `/mods`, and cmod checks every call and every answer against what they granted.
+
+Permissions bind every mod built on `@cmodjs/core`, and the plugin directory reads them from `package.json`. They are a contract, not a sandbox: a Claude Code plugin can skip cmod and call Claude Code directly.
+
+## Declare the permissions
+
+They sit in the `package.json` `cmod` key, beside `install` and `keys`, because the person reads them before any of the mod's code runs:
+
+```json
+"cmod": {
+  "permissions": { "network": ["api.github.com"], "run": ["gh"], "prompt": true, "model": true }
+}
+```
+
+| Permission | The person reads | cmod checks |
+| --- | --- | --- |
+| `"network": ["api.github.com"]` | Connect to api.github.com | `mod.http.fetch` to that host. A path starting with `/` or `~/` names a socket, such as `"~/.docker/run/docker.sock"` |
+| `"run": ["gh"]`, or `"run": "*"` | Run gh on your computer | `mod.process.run`, `mod.process.spawn`, and the `program` and `check` jobs. A program matches by its file name, so `"mermaid-ascii"` covers `${mod.dataFolder}/bin/mermaid-ascii` |
+| `"files": ["~/.zshrc"]` | Change ~/.zshrc | `mod.fs.write` and `mod.metadata.update` outside the project and the mod's data folder. A folder covers every file below it |
+| `"conversation": true` | Read this conversation | `mod.session.messages`, and reading Claude Code's transcript files |
+| `"prompt": true` | Add text Claude reads and start turns | `mod.session.append`, `mod.session.submit`, the `prompt` and `schedule` jobs, and the hook answers listed below |
+| `"model": true` | Ask a model, which uses your plan | `mod.model.complete` |
+| `"agents": true` | Start agents | `mod.agent.spawn` |
+| `"tools": true` | Use and change Claude's tool calls | `mod.claude.tool.call`, and a hook that changes a tool call's input |
+| `"config": true` | Change your Claude Code settings | `mod.claude.config.set`, and writes to `.claude/settings.json`, `.claude/settings.local.json`, and `.mcp.json` |
+| `"approve": true` | Approve Claude's tool calls for you | an allow or an ask from the mod's permission rules or hooks, and a `retry`. A deny needs no permission |
+
+Reading files, drawing panes and slot renders, toasts, slash commands, tools of the mod's own, and hooks need no permission.
+
+`cmod check` adds `"approve": true` to `package.json` when `hooks/register.ts` calls `registerPermissionCheck` and the line is missing, and says so.
+
+## What the person sees
+
+The install opens the installer pane in Claude Code and lists every permission in `permissions`, with the install step, the program, and the keys. An update asks again only when it adds a permission, and lists only the new ones. Removing the mod revokes everything it was granted.
+
+`/mods <mod>` lists the same permissions as toggles. A toggle runs `cmod permission <mod> <name> [value] on|off`, and the mod sees the change before its next call, with no reload.
+
+`cmod check` prints the sentences, so you read what the person will see:
+
+```text
+✔ At install the person grants: Connect to api.github.com; Run gh on your computer; Ask a model, which uses your plan
+```
+
+## Check a permission before a feature uses it
+
+```ts
+mod.permissions.has(name: 'network' | 'run' | 'files', value: string): boolean
+mod.permissions.has(name: 'conversation' | 'prompt' | 'model' | 'agents' | 'tools' | 'config' | 'approve'): boolean
+```
+
+`has` says whether the person has the permission turned on, so a mod hides a feature instead of failing it:
+
+```ts
+if (mod.permissions.has('model')) {
+  const verdict = await mod.model.complete({ prompt: 'Is this reply a waste of time?' })
+}
+```
+
+## When a call has no grant
+
+The call rejects, and the error names the fix:
+
+- An undeclared call names the line to add: `ci-watch calls http.fetch(https://api.github.com/repos), which needs "permissions": { "network": ["api.github.com"] } in package.json "cmod".`
+- A declared call the person turned off names where to turn it on: `ci-watch calls model.complete without your grant to "Ask a model, which uses your plan". Turn it on in /mods ci-watch.`
+- A `program` job without its grant stops at once with the same line, with no restarts.
+
+## When a hook answer has no grant
+
+cmod checks the answer each hook returns, part by part. A part without its grant is dropped, and cmod logs once per permission which part it dropped and how to fix it:
+
+```text
+ci-watch answered additionalContext without your grant to "Add text Claude reads and start turns", so cmod dropped it. Turn it on in /mods ci-watch.
+```
+
+| Answer part | Permission |
+| --- | --- |
+| `additionalContext`, `initialUserMessage`, `suppressOriginalPrompt`, `updatedToolOutput`, a `prompt` job's text | `prompt` |
+| a Stop or PostToolUse block | `prompt` |
+| `updatedInput`, and a changed tool input passed down the chain | `tools` |
+| an allow or an ask, and `retry` | `approve` |
+
+A deny needs no permission. A tool of the mod's own, `mcp__<mod>__*`, answers freely.
+
+## Test permissions
+
+`testMod` grants what the mod's `package.json` declares, so tests run as an installed mod does. An undeclared call fails the test with the line to add. `testMod(mod, { permissions: ['network:api.github.com'] })` grants exactly the list instead, so a test checks what happens with a permission turned off ([testing.md](testing.md)).

package/docs/state.md

@@ -80,16 +80,11 @@ export const reads = defineMod({
 
 ## Where the values come from
 
-When the mod starts, each value is, in order of precedence:
+When the mod starts, each value is the value the mod saved for this session, this project, or globally, or else the starting value in `defineMod`. After a `/cd` to another project, cmod loads that project's `project` values.
 
-1. The value the mod saved for this session, this project, or globally.
-2. The value in the project's `state.json`.
-3. The value in the person's own `state.json`.
-4. The starting value in `defineMod`.
+`mod.state` holds what the mod owns and changes as it runs. What a person sets, such as a token or a branch to watch, is an option ([options.md](options.md)).
 
-After a `/cd` to another project, cmod loads that project's `project` values and reads its `state.json` again.
-
-## Let a person change the starting values
+## Let a person replace a Skill's text
 
 Each mod has two config folders, outside its code:
 
@@ -98,29 +93,7 @@ Each mod has two config folders, outside its code:
 <project>/.claude/cmods/<mod>/      the team's, committed with the repository
 ```
 
-`CLAUDE_CONFIG_DIR` moves `~/.claude`. Removing the mod keeps both folders.
-
-A `state.json` in either folder lists only the values to change:
-
-```json
-{ "global": { "defaultCommitPolicy": "never" }, "session": { "prompts": 10 } }
-```
-
-- A `session` value is what each new conversation starts with. A `project` value is what each project starts with.
-- A file in the project folder wins over the same value in the person's folder.
-- A project `state.json` cannot set `global` values, because one repository cannot change a value for every project.
-- A file cannot set `memory` values.
-
-cmod ignores each entry it cannot use and logs one line naming the file, the entry, and the fix:
-
-- a file that is not JSON, or not a JSON object
-- a group the mod does not declare
-- a key the mod does not declare
-- a value whose type differs from the starting value's
-- a `global` value in a project file
-- a `memory` value
-
-## Let a person replace a Skill's text
+`CLAUDE_CONFIG_DIR` moves `~/.claude`. Removing the mod keeps both folders. The project folder also holds the team's options, in `options.json` ([options.md](options.md)).
 
 A person replaces the text of a Skill the mod ships by putting a file at the same path in a config folder:
 

package/docs/testing.md

@@ -3,7 +3,7 @@
 `testMod` runs a mod against a fake Claude Code in `bun test`, so a test drives the mod the way a person and Claude do and reads what they would see. It needs no running Claude Code.
 
 ```ts
-testMod<State>(definition: ModDefinition<State>, options?: TestOptions<State>): TestedMod<State>
+testMod<State, Options>(definition: ModDefinition<State, string, Options>, options?: TestOptions<State, Options>): TestedMod<State>
 ```
 
 ```ts
@@ -24,24 +24,30 @@ Assert what a person or Claude sees: `tested.lines(...)`, `tested.shown`, `teste
 ## TestOptions
 
 ```ts
-type TestOptions<State> = {
+type TestOptions<State, Options> = {
   readonly state?: { [Lifetime in keyof State]?: Partial<State[Lifetime]> }
+  readonly options?: Partial<OptionValues<Options>>
+  readonly permissions?: readonly string[]
   readonly scope?: 'user' | 'project'
   readonly projectRoot?: string
   readonly cwd?: string
   readonly dependencies?: { [Name in keyof CmodDependencies]?: CmodDependencies[Name] }
   readonly files?: Readonly<Record<string, string>>
+  readonly links?: Readonly<Record<string, string>>
 }
 ```
 
 | Option | What it sets | Default |
 | --- | --- | --- |
 | `state` | Values over the declared starting state | The declared state |
+| `options` | The option values Claude Code passes, as a person set them ([options.md](options.md)) | none: each option gets its default |
+| `permissions` | Exactly the permissions the person granted, such as `['network:api.github.com', 'model']` ([permissions.md](permissions.md)) | every permission the mod's `package.json` declares |
 | `scope` | `'project'` makes the mod a project plugin, in `<projectRoot>/.claude/skills/<name>` | `'user'` |
 | `projectRoot` | `mod.projectRoot` | `/test/plugins/<name>`, or `/test/project` for a project plugin |
 | `cwd` | `mod.cwd` | `projectRoot` |
 | `dependencies` | The methods other mods answer with | none: every call fails with `<name> is not installed. Run cmod install <name>.` |
 | `files` | The fake file system, absolute path to text | no files |
+| `links` | Symbolic links in the fake file system, absolute link path to its target | no links |
 
 A project plugin finds its repository through a `.git` entry at `projectRoot`, so a test of one puts it in `files`, such as `files: { '/test/project/.git': '' }`. Without it the project plugin has no repository, and its rules match calls in every folder, as a user mod's do.
 
@@ -213,6 +219,7 @@ type Fakes = {
   fs: { read?, write?, list?, exists?, stat? }
   http: { fetch? }
   settings: { read? }
+  config: { list?, set? }
   ui: { ask?, open?, scroll? }
   session: { messages?, append? }
   prompt: { submit? }
@@ -234,7 +241,11 @@ Set a fake to answer a call:
 - `clock.after(ms, fn)` and `clock.every(ms, fn)` each return `{ cancel() }`, and so must a fake of either. `clock.after` runs a real timer by default. `clock.every` never fires unless a fake keeps `fn` for the test to call, so a test of `mod.every` keeps it and calls it once per tick.
 - `session.append` and `prompt.submit` take every note and prompt by default, into `shown.notes` and `shown.prompts`. A fake that answers `{ deny }` or `{ drop }` refuses one.
 - `model.complete` has no default: set it to the answer the model gives, such as `async () => ({ isAnswered: true, text: 'no', usage })`.
+- `config.list` answers no `/config` rows by default, and `config.set` answers every change with `{ value }`. A `config.list` fake that answers a row with `isLocked: true` locks that option as managed settings do.
 - `tool.call` answers `CronCreate`, `CronDelete`, and `CronList` by default, keeping the crons a `schedule` makes in `shown.schedules`. A call to any other tool needs a fake.
+- `files` takes symbolic links too: `testMod(mod, { files, links: { '/work/skills': '/shared/skills' } })` makes `/work/skills` a link to `/shared/skills`, so a test of `mod.fs.find` or `mod.metadata.update` follows it as a real file system does.
+- `testMod` runs no installer pane: an option with no default and no value fails `start()` with its fix, and the `installer` steps are not shown. Test a step's `render` and `isDone` by calling them with the started `mod`.
+- The `committer` below runs `git`, so its `package.json` declares `"permissions": { "run": ["git"] }`. A gated call the mod does not declare fails before it reaches a fake ([permissions.md](permissions.md)).
 
 ```ts
 import { expect, test } from 'bun:test'

package/installer.d.ts

@@ -0,0 +1,10 @@
+import type { Frozen, RenderElement, RenderPropsOf } from 'claude-code';
+import type { Mod } from './mod.js';
+export type Step<State extends object = Record<never, never>> = {
+    readonly id: string;
+    readonly title: string;
+    render(mod: Mod<State>, props: Frozen<RenderPropsOf['Pane']>): RenderElement;
+    isDone(mod: Mod<State>): boolean | Promise<boolean>;
+};
+export declare function defineStep<State extends object = Record<never, never>>(step: Step<State>): Step<State>;
+//# sourceMappingURL=installer.d.ts.map

package/installer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["src/installer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AACvE,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAA;AAEnC,MAAM,MAAM,IAAI,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI;IAC9D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,GAAG,aAAa,CAAA;IAC5E,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CACpD,CAAA;AAID,wBAAgB,UAAU,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAItG"}

package/installer.js

@@ -0,0 +1,8 @@
+const stepId = /^[A-Za-z0-9_-]{1,64}$/;
+export function defineStep(step) {
+    if (!stepId.test(step.id))
+        throw new Error(`defineStep: "${step.id}" is not a step id. Use 1 to 64 letters, digits, "_", or "-".`);
+    if (step.title.trim() === '')
+        throw new Error(`defineStep: the step "${step.id}" needs a title, the line the installer shows above it.`);
+    return step;
+}

package/jobs/context.d.ts

@@ -3,12 +3,12 @@ import { type Deadline } from '../runtime/deadline.js';
 import type { ToolCall } from '../utils/call-effects.js';
 import { type Workspace } from './permissions/find-project-scope.js';
 import { type Target } from './permissions/match-target.js';
-export declare function workspaceReader({ claude }: JobContext): () => Promise<Workspace>;
+export declare function workspaceReader({ mod: { claude } }: JobContext): () => Promise<Workspace>;
 export declare function afterCall<State extends object>(job: JobContext<State>, contextAfter: (call: ToolCall, workspace: Workspace) => Promise<readonly string[]>, failed: (error: unknown) => readonly string[]): void;
 export declare function modOf<State extends object>(job: JobContext<State>, { call, folder }: {
     readonly call?: ToolCall;
     readonly folder: string;
 }, workspace: Workspace, deadline: Deadline): Mod<State>;
-export declare function modWithin<State extends object>({ mod, claude }: JobContext<State>, deadline: Deadline, workTree?: () => Promise<string | undefined>): Mod<State>;
+export declare function modWithin<State extends object>({ mod }: JobContext<State>, deadline: Deadline, workTree?: () => Promise<string | undefined>): Mod<State>;
 export declare function targetWords(target: Target): string;
 //# sourceMappingURL=context.d.ts.map

package/jobs/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/jobs/context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,WAAW,CAAA;AAEhD,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAItE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AACxD,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,qCAAqC,CAAA;AACtF,OAAO,EAAY,KAAK,MAAM,EAAE,MAAM,+BAA+B,CAAA;AAOrE,wBAAgB,eAAe,CAAC,EAAE,MAAM,EAAE,EAAE,UAAU,GAAG,MAAM,OAAO,CAAC,SAAS,CAAC,CAOhF;AAaD,wBAAgB,SAAS,CAAC,KAAK,SAAS,MAAM,EAC5C,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC,EACtB,YAAY,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,KAAK,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,EAClF,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,SAAS,MAAM,EAAE,GAC5C,IAAI,CAUN;AAMD,wBAAgB,KAAK,CAAC,KAAK,SAAS,MAAM,EAAE,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,CAEjM;AAED,wBAAgB,SAAS,CAAC,KAAK,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,UAAU,CAAC,KAAK,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,GAAE,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAyB,GAAG,GAAG,CAAC,KAAK,CAAC,CA0BvL;AAwBD,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CASlD"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/jobs/context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,WAAW,CAAA;AAEhD,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAItE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AACxD,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,qCAAqC,CAAA;AACtF,OAAO,EAAY,KAAK,MAAM,EAAE,MAAM,+BAA+B,CAAA;AAOrE,wBAAgB,eAAe,CAAC,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,UAAU,GAAG,MAAM,OAAO,CAAC,SAAS,CAAC,CAOzF;AAaD,wBAAgB,SAAS,CAAC,KAAK,SAAS,MAAM,EAC5C,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC,EACtB,YAAY,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,KAAK,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,EAClF,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,SAAS,MAAM,EAAE,GAC5C,IAAI,CAUN;AAMD,wBAAgB,KAAK,CAAC,KAAK,SAAS,MAAM,EAAE,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,CAEjM;AAED,wBAAgB,SAAS,CAAC,KAAK,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,EAAE,UAAU,CAAC,KAAK,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,GAAE,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAyB,GAAG,GAAG,CAAC,KAAK,CAAC,CA4B/K;AAwBD,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CASlD"}