@cmodjs/core 0.1.6 → 0.1.8

package/README.md

@@ -4,7 +4,7 @@
 
 # @cmodjs/core
 
-The library every Claude Mod Manager mod imports. Claude Mod Manager (CMod) installs, tries, builds, checks, and publishes Claude Code mods: plugins with hooks, panes, slash commands, tools, permission rules, and an install step that runs with your consent.
+The library every Claude Mod Manager mod imports. Claude Mod Manager (cmod) installs, tries, builds, checks, and publishes Claude Code mods: plugins with hooks, panes, slash commands, tools, permission rules, and an install step that runs with your consent.
 
 ```sh
 npm i -g @cmodjs/cli
@@ -17,4 +17,4 @@ cmod new my-mod
 
 This package ships its docs in `docs/`, so a mod's `node_modules/@cmodjs/core/docs/index.md` is the map of the docs for the version it installed. The same docs are on GitHub at [core/docs](https://github.com/heyJordanParker/cmod/blob/main/core/docs/index.md).
 
-The CMod plugin and the `cmod` source live at [github.com/heyJordanParker/cmod](https://github.com/heyJordanParker/cmod).
+The cmod plugin and the `cmod` source live at [github.com/heyJordanParker/cmod](https://github.com/heyJordanParker/cmod).

package/docs/commands.md

@@ -1,6 +1,6 @@
 # cmod commands
 
-The `cmod` command of Claude Mod Manager (CMod) builds, checks, and publishes mods, and installs them. `npm i -g @cmodjs/cli` puts it on `PATH`. `cmod <command> --help` prints a command's arguments, and `cmod --version` prints the version.
+The `cmod` command of Claude Mod Manager (cmod) builds, checks, and publishes mods, and installs them. `npm i -g @cmodjs/cli` puts it on `PATH`. `cmod <command> --help` prints a command's arguments, and `cmod --version` prints the version.
 
 Each command below restates what `cmod <command> --help` prints, for a mod author. The help text is the full word.
 
@@ -25,7 +25,7 @@ Creates a mod in `./<name>`: a `defineMod` with one hook, one pane, and one rend
 cmod link [path] [--yes]
 ```
 
-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`.
+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.
 
@@ -57,7 +57,7 @@ Runs every check this machine can run on the mod at `path` (default: the current
 10. Runs, with `claude plugin test`, the test files that import `claude-code/testing`. It skips this when none does.
 11. 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 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
 
@@ -65,7 +65,7 @@ Runs every check this machine can run on the mod at `path` (default: the current
 cmod try <owner/repo | path> [--yes] [-- claude arguments]
 ```
 
-Starts one throwaway Claude Code session with a mod set up. Installs the mod's packages, installs the CMod plugin when Claude Code lacks it, and runs the mod's install step after asking consent. Then starts one Claude Code session with the mod loaded through `--plugin-dir`.
+Starts one throwaway Claude Code session with a mod set up. Installs the mod's packages, installs the cmod plugin when Claude Code lacks it, and runs the mod's install step after asking consent. Then starts one Claude Code session with the mod loaded through `--plugin-dir`.
 
 - Unlike `cmod link`, it builds no program from `cli/`. A mod whose `package.json` `cmod.program` names a program downloads it from the GitHub release of the mod's version, so it fails until `cmod publish` has released that version.
 
@@ -82,12 +82,12 @@ cmod publish [path] [--dry-run]
 
 Releases the mod at `path` (default: the current folder) at the version in its `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 `.claude-plugin/`, `package.json`, the README, and the license, the way `npm publish` reads it. 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, 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.
+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`, the README, and the license, the way `npm publish` reads it. 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.
+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.
 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`.
 
@@ -103,7 +103,7 @@ 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
+- 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 and writes everything, and pushes nothing. 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.
@@ -117,7 +117,7 @@ cmod install <owner/repo | path> [name] [--yes]
 cmod install <name | name@marketplace> [--yes]
 ```
 
-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.
+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.
 
 - When the marketplace lists several plugins, name the one to install after it.
 - Given `name@marketplace` of a marketplace Claude Code has added, it installs that plugin.
@@ -141,7 +141,7 @@ Updates the named plugin, or every plugin Claude Code has installed, through Cla
 cmod remove <name>
 ```
 
-Uninstalls the plugin through Claude Code. When CMod set the plugin up as a mod, it then runs the uninstall step CMod saved and removes what CMod set up.
+Uninstalls the plugin through Claude Code. When cmod set the plugin up as a mod, it then runs the uninstall step cmod saved and removes what cmod set up.
 
 ### cmod list
 
@@ -149,9 +149,9 @@ Uninstalls the plugin through Claude Code. When CMod set the plugin up as a mod,
 cmod list
 ```
 
-Lists every plugin Claude Code has installed or linked, with its version. A mod shows whether CMod set it up, and any other plugin shows whether Claude Code enabled it. It also lists every mod Claude Code removed whose uninstall step has not run yet.
+Lists every plugin Claude Code has installed or linked, with its version. A mod shows whether cmod set it up, and any other plugin shows whether Claude Code enabled it. It also lists every mod Claude Code removed whose uninstall step has not run yet.
 
-- The `cmod` commands count a plugin as a mod only when its `package.json` has a `cmod` step key or CMod holds an install record for it. A mod made with `cmod new` has neither until its first Claude Code session sets it up, so until then `cmod list` shows it as `enabled`, like any other plugin.
+- The `cmod` commands count a plugin as a mod only when its `package.json` has a `cmod` step key or cmod holds an install record for it. A mod made with `cmod new` has neither until its first Claude Code session sets it up, so until then `cmod list` shows it as `enabled`, like any other plugin.
 
 ## Run in an install script
 
@@ -163,9 +163,9 @@ cmod download <program> <machine> <url> <sha256> [<machine> <url> <sha256> …]
 
 Downloads a program for an install script: fetches the download for this machine, checks its SHA-256, unpacks it, and moves `<program>` to `$CMOD_DATA/bin/<program>`. [install-steps.md](install-steps.md) explains it.
 
-## Run by CMod
+## 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 two itself. A person runs them to see a step's whole log or to finish a step.
 
 ### cmod setup
 

package/docs/dependencies.md

@@ -24,7 +24,7 @@ export const tracer = defineMod({
 
 ## Type the methods: CmodDependencies
 
-The provider types its `api` in `types/index.d.ts`, and its `.claude-plugin/plugin.json` names that file as `"types": "./types/index.d.ts"`. The file adds the mod to `CmodDependencies`, which the Claude Mod Manager (CMod) plugin declares on the `claude-code` module:
+The provider types its `api` in `types/index.d.ts`, and its `.claude-plugin/plugin.json` names that file as `"types": "./types/index.d.ts"`. The file adds the mod to `CmodDependencies`, which the Claude Mod Manager (cmod) plugin declares on the `claude-code` module:
 
 ```ts
 export type TracerSignature = { name: string; line: number }

package/docs/hooks.md

@@ -12,6 +12,8 @@ type ModHook<E> = (input: HookInputs[E]) => HookAnswer | void | Promise<HookAnsw
 
 Add hooks in `setup`. Each `mod.on` adds one more hook. Several hooks on one event all run.
 
+A hook on `PreToolUse` or `PermissionRequest` takes part in Claude Code's permission check, so the mod's `hooks/register.ts` calls `registerPermissionCheck(addHook)` after `registerMod` ([mod.md](mod.md)). Without it the mod does not start.
+
 ```ts
 import { defineMod } from '../node_modules/@cmodjs/core/mod.js'
 
@@ -37,7 +39,7 @@ export const safeDelete = defineMod({
 | `SessionEnd` | none |
 | `UserPromptSubmit` | none |
 | `InstructionsLoaded` | none |
-| `PreToolUse` | Claude Mod Manager (CMod) builds the input: `session_id`, `cwd`, `hook_event_name`, `tool_name`, `tool_input`, `tool_use_id`, `agent_id` inside a subagent, `agent_type` inside a subagent or when the session started as an agent, and `files`. It has no `transcript_path` and no `permission_mode`. |
+| `PreToolUse` | Claude Mod Manager (cmod) builds the input: `session_id`, `cwd`, `hook_event_name`, `tool_name`, `tool_input`, `tool_use_id`, `agent_id` inside a subagent, `agent_type` inside a subagent or when the session started as an agent, and `files`. It has no `transcript_path` and no `permission_mode`. |
 | `PermissionRequest` | none |
 | `PermissionDenied` | none |
 | `PostToolUse` | adds `files` |
@@ -51,17 +53,17 @@ export const safeDelete = defineMod({
 | `StopFailure` | none |
 | `CwdChanged` | no `transcript_path` |
 
-CMod raises `CwdChanged` itself, never Claude Code. It raises it when the working folder changes: after `/cd`, after a Bash or PowerShell call, and at a prompt. `mod.cwd` and `mod.projectRoot` already hold the new folder when the hook runs.
+cmod raises `CwdChanged` itself, never Claude Code. It raises it when the working folder changes: after `/cd`, after a Bash or PowerShell call, and at a prompt. `mod.cwd` and `mod.projectRoot` already hold the new folder when the hook runs.
 
 ## files: what a tool call reads and changes
 
-The input of `PreToolUse`, `PostToolUse`, and `PostToolUseFailure` has `files: { read: string[]; changed: string[] }`, absolute paths that CMod works out from the call:
+The input of `PreToolUse`, `PostToolUse`, and `PostToolUseFailure` has `files: { read: string[]; changed: string[] }`, absolute paths that cmod works out from the call:
 
 - `Read` reads its `file_path`. `Edit`, `Write`, and `NotebookEdit` change their path.
 - `Grep` counts its `path`, or the working folder when it names none, and `Glob` counts its `pattern` joined to its `path`. Since `read` lists only files, a `Grep` of a folder and every `Glob` usually leave `read` empty.
 - A `Bash` command reads and changes the files its commands name, such as `cat a.ts > b.ts`. A path that holds a shell expansion, such as `$HOME`, is left out.
 - `read` lists only paths that are files now. `changed` lists every path the call writes, whether it exists or not.
-- When CMod cannot work the files out, both lists are empty, and the reason goes to Claude Code's debug log.
+- When cmod cannot work the files out, both lists are empty, and the reason goes to Claude Code's debug log.
 
 ## HookAnswer: what a hook can answer
 
@@ -97,7 +99,7 @@ type HookAnswer = {
 - `continue: false` stops the session after the event, and `stopReason` is the text Claude Code shows. `PreToolUse` takes neither.
 - `decision: 'block'` with a `reason` blocks the event. On `PreToolUse` it denies the call with the reason. On `Stop` it keeps Claude going with the reason.
 - `systemMessage` shows the text to the person as a log line.
-- CMod ignores `suppressOutput`.
+- cmod ignores `suppressOutput`.
 - `hookSpecificOutput.hookEventName` is optional. When set, it must be the event's own name.
 
 Each event reads only some `hookSpecificOutput` fields:
@@ -145,11 +147,11 @@ A hook that throws, rejects, or answers a field its event does not read fails:
 
 - On `PreToolUse` the call is denied with `<mod>: the PreToolUse hook failed: <error>`.
 - On `PermissionRequest` the request is denied with `<mod>: the PermissionRequest hook failed: <error>`.
-- On every other event CMod logs `<mod>: the <event> hook failed: <error>`, and the event goes on as if the hook answered nothing.
+- On every other event cmod logs `<mod>: the <event> hook failed: <error>`, and the event goes on as if the hook answered nothing.
 
 ## The first SessionStart
 
-A mod that is still installing when the session starts misses Claude Code's `SessionStart`. CMod holds `SessionStart` up to 9 seconds for the mod to start. When the mod starts later, CMod runs its `SessionStart` hooks then, and Claude Code no longer reads their answer.
+A mod that is still installing when the session starts misses Claude Code's `SessionStart`. cmod holds `SessionStart` up to 9 seconds for the mod to start. When the mod starts later, cmod runs its `SessionStart` hooks then, and Claude Code no longer reads their answer.
 
 ## Test a hook
 

package/docs/index.md

@@ -4,7 +4,7 @@ These are the docs of the `@cmodjs/core` version installed beside them. Read the
 
 ## What a mod is
 
-A mod is a Claude Code plugin built with `@cmodjs/core`. Claude Mod Manager (CMod) installs mods, runs their install and uninstall steps with the person's consent, and builds and publishes new ones. The `cmod` command does that work in a terminal.
+A mod is a Claude Code plugin built with `@cmodjs/core`. Claude Mod Manager (cmod) installs mods, runs their install and uninstall steps with the person's consent, and builds and publishes new ones. The `cmod` command does that work in a terminal.
 
 `cmod new my-mod` writes this layout:
 
@@ -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                   connect(on, myMod), and nothing else
+├── hooks/register.ts                   registerMod(addHook, myMod), 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
@@ -74,7 +74,7 @@ A mod imports from the files below, and every other file in this package is inte
 | `mod.js` | `Claude`, `RoutedEvent`, `RoutedHook`, `ToolCalls` | [jobs.md](jobs.md) |
 | `mod.js` | `ModEvent`, `ModHook`, `HookAnswer` | [hooks.md](hooks.md) |
 | `mod.js` | `notInstalled` | [dependencies.md](dependencies.md) |
-| `connect.js` | `connect` | [mod.md](mod.md) |
+| `register.js` | `registerMod`, `registerPermissionCheck` | [mod.md](mod.md) |
 | `testing.js` | `testMod`, `TestOptions`, `TestInput`, `TestedMod`, `Fakes`, `Shown`, `TestCall` | [testing.md](testing.md) |
 | `ui/define-pane.js` | `definePane`, `Pane` | [ui.md](ui.md) |
 | `ui/elements.js` | `Box`, `Text`, `Button`, `Link`, `Code`, `Markdown`, `Input`, `Select`, `Image`, `drawWith` | [ui.md](ui.md) |

package/docs/install-steps.md

@@ -1,6 +1,6 @@
 # Install steps
 
-A mod that changes the machine, such as by adding a shell alias or downloading a program, names its install and uninstall steps in its `package.json`. The cmod program of Claude Mod Manager (CMod) runs them with the person's consent, and runs the uninstall step after the person removes the mod. The library never runs them.
+A mod that changes the machine, such as by adding a shell alias or downloading a program, names its install and uninstall steps in its `package.json`. The cmod program of Claude Mod Manager (cmod) runs them with the person's consent, and runs the uninstall step after the person removes the mod. The library never runs them.
 
 ## The cmod key
 
@@ -18,20 +18,20 @@ Each key is optional.
 
 - `install` is one shell command that sets the mod up.
 - `uninstall` is one shell command that undoes it.
-- `program` is the name of a program CMod downloads from the mod's GitHub release into `~/.local/bin`. [Ship a program](#ship-a-program) explains it.
+- `program` is the name of a program cmod downloads from the mod's GitHub release into `~/.local/bin`. [Ship a program](#ship-a-program) explains it.
 
-CMod refuses a `cmod` key that breaks these rules, with the fix in the message:
+cmod refuses a `cmod` key that breaks these rules, with the fix in the message:
 
 - `cmod` is an object.
 - `install` and `uninstall` are each one command on one line, with no tab.
-- Each names at least one script file inside the mod, and no script at the mod's root. CMod asks consent for the whole folder of each script, so put the scripts in a folder, such as `setup/`.
+- Each names at least one script file inside the mod, and no script at the mod's root. cmod asks consent for the whole folder of each script, so put the scripts in a folder, such as `setup/`.
 - A symbolic link in a script folder points at a file.
 - `program` is a command name: letters, digits, `.`, `_`, and `-`, starting with a letter or digit.
 - `.claude-plugin/plugin.json` has a `version`.
 
 ## Consent
 
-Before a step runs for the first time, CMod shows the person the commands and asks to run them. CMod hashes the commands and every file in each script folder, and remembers the hash the person approved. A change to any of those files asks again.
+Before a step runs for the first time, cmod shows the person the commands and asks to run them. cmod hashes the commands and every file in each script folder, and remembers the hash the person approved. A change to any of those files asks again.
 
 - In Claude Code, the mod asks `<mod> runs <install> to install, and <uninstall> when you remove it. Run it now?` with `Install` and `Not now`. A progress line above the prompt shows the install.
 - 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.`
@@ -42,14 +42,14 @@ The mod starts only once its install step has run ([mod.md](mod.md)).
 
 ## How a step runs
 
-CMod runs a step with `sh -c "<command>"` in the mod's folder. So `./setup/install.sh` runs the script itself, and the script must be executable: `chmod +x setup/*.sh`.
+cmod runs a step with `sh -c "<command>"` in the mod's folder. So `./setup/install.sh` runs the script itself, and the script must be executable: `chmod +x setup/*.sh`.
 
 The step gets these environment variables:
 
 | Variable | Value |
 | --- | --- |
 | `CMOD_PLUGIN_ROOT` | The mod's folder |
-| `CMOD_DATA` | The mod's data folder, which CMod creates first. It is the folder `mod.dataFolder` names. |
+| `CMOD_DATA` | The mod's data folder, which cmod creates first. It is the folder `mod.dataFolder` names. |
 | `CMOD_VERSION` | The mod's version from `plugin.json` |
 | `PATH` | The person's `PATH`, with the cmod program's own folder first, so the step can run `cmod download` |
 
@@ -63,18 +63,18 @@ The install step runs again on every new version of the mod and whenever its scr
 
 ## When the install step fails
 
-- When the first install of a mod fails or is stopped, CMod runs the uninstall step to undo it. So the uninstall step must work on a partial install.
-- When the install step of an upgrade fails or is stopped, CMod keeps the version it set up before.
+- When the first install of a mod fails or is stopped, cmod runs the uninstall step to undo it. So the uninstall step must work on a partial install.
+- When the install step of an upgrade fails or is stopped, cmod keeps the version it set up before.
 - The failure shows on the mod's progress line with `Fix the cause, then run: cmod install <mod>`.
 
 ## The uninstall step
 
-When the install step succeeds, CMod saves a copy of every script folder the uninstall step names. It runs the uninstall step from that copy, so it runs after the mod's own folder is gone.
+When the install step succeeds, cmod saves a copy of every script folder the uninstall step names. It runs the uninstall step from that copy, so it runs after the mod's own folder is gone.
 
-- After the person removes the mod with `/plugin uninstall`, the CMod plugin runs the uninstall step at the next session start or prompt.
+- After the person removes the mod with `/plugin uninstall`, the cmod plugin runs the uninstall step at the next session start or prompt.
 - `cmod remove <mod>` uninstalls the mod and runs the step at once.
 - In the copy, `CMOD_PLUGIN_ROOT` is the copy's folder, and `CMOD_DATA` and `CMOD_VERSION` are the same as at install.
-- After the step, CMod deletes the mod's install record, its program, its data folder, and the approvals of its scripts. It keeps the mod's config folders, because the files there are the person's.
+- After the step, cmod deletes the mod's install record, its program, its data folder, and the approvals of its scripts. It keeps the mod's config folders, because the files there are the person's.
 - A failed uninstall step keeps the record. `cmod teardown <mod>` runs it again.
 
 ## Example
@@ -102,7 +102,7 @@ cat "$kept" > "$HOME/.zshrc"
 rm "$kept"
 ```
 
-CMod deletes `$CMOD_DATA` itself after the uninstall step.
+cmod deletes `$CMOD_DATA` itself after the uninstall step.
 
 ## Download a program in an install step
 
@@ -122,7 +122,7 @@ cmod download mermaid-ascii \
 
 ## Ship a program
 
-A mod that builds its own command-line program keeps its source in `cli/`, and CMod builds it, releases it, and puts it on the person's `PATH`.
+A mod that builds its own command-line program keeps its source in `cli/`, and cmod builds it, releases it, and puts it on the person's `PATH`.
 
 1. `cli/package.json` declares the build:
 
@@ -144,8 +144,8 @@ Then:
 
 - `cmod link` builds the program and links this machine's build to `~/.local/bin/<program>`.
 - `cmod publish` builds every machine's file and attaches each to the GitHub release `v<version>`, with a `SHA256SUMS` file. It refuses a `cli/` program that the `package.json` `program` key does not name.
-- On install, CMod downloads `<repository>/releases/download/v<version>/<program>-<machine>`, checks it against `SHA256SUMS`, runs `<program> --version`, and links it to `~/.local/bin/<program>`.
-- CMod refuses to replace a `~/.local/bin/<program>` it did not make, and a program `PATH` already finds somewhere else.
+- On install, cmod downloads `<repository>/releases/download/v<version>/<program>-<machine>`, checks it against `SHA256SUMS`, runs `<program> --version`, and links it to `~/.local/bin/<program>`.
+- cmod refuses to replace a `~/.local/bin/<program>` it did not make, and a program `PATH` already finds somewhere else.
 - `cmod unlink` and the uninstall remove the program.
 
-The CMod repository ships the `cmod` program this way. Its `package.json` holds `"cmod": { "program": "cmod" }`, and its `cli/package.json` holds `"cmod": { "build": "bun run build", "output": "dist" }`.
+The cmod repository ships the `cmod` program this way. Its `package.json` holds `"cmod": { "program": "cmod" }`, and its `cli/package.json` holds `"cmod": { "build": "bun run build", "output": "dist" }`.

package/docs/jobs.md

@@ -22,7 +22,7 @@ A job's bad options throw at one of two times. `check`, `permissions`, and `prom
 | `statusLine` | `jobs/status-line.js` | A status line |
 | `program` | `jobs/program.js` | A background program the mod talks to over HTTP |
 
-Each job announces itself. The first time a version starts, Claude Mod Manager (CMod) logs what the mod added, such as `tasks added /tasks, the open_ticket tool and 2 permission rules.`
+Each job announces itself. The first time a version starts, Claude Mod Manager (cmod) logs what the mod added, such as `tasks added /tasks, the open_ticket tool and 2 permission rules.`
 
 ## Deadlines
 
@@ -57,11 +57,11 @@ type Reply = string | { text?: string; context?: string } | undefined
 - `description` is the line the typeahead and `/help` show.
 - `argumentHint` is drawn dim after the name, such as `[path]`.
 - `immediate: true` runs the command at once while Claude is still working. Without it, the command waits for the turn to end.
-- `reply` gets `args` and `positionals`. `args` is everything after the name as Claude Code passes it, and `''` for a bare `/<name>`. CMod hands it on unchanged. `positionals` is that text split into words the way a shell splits them, so extra spaces never reach it. `tested.type('/todo  milk')` drops the spaces after the name.
+- `reply` gets `args` and `positionals`. `args` is everything after the name as Claude Code passes it, and `''` for a bare `/<name>`. cmod hands it on unchanged. `positionals` is that text split into words the way a shell splits them, so extra spaces never reach it. `tested.type('/todo  milk')` drops the spaces after the name.
 - A `string` reply, or `text`, shows as the command's output. `context` is text Claude reads after the output, and the person never sees. `undefined` shows nothing.
 - A `reply` that throws shows `/<name> failed: <error>`.
 - Two commands with one name in a mod throw `<mod>: the slash command /<name> is already added. Give each slashCommand its own name.`
-- When Claude Code refuses to add the command, CMod logs `<mod>: /<name> is not added: <error>`.
+- When Claude Code refuses to add the command, cmod logs `<mod>: /<name> is not added: <error>`.
 
 ```ts
 import { defineMod } from '../node_modules/@cmodjs/core/mod.js'
@@ -99,7 +99,7 @@ tool<Schema, State>(options: {
 
 - `name` is 1 to 64 letters, digits, `_`, or `-`. Claude sees the tool as `mcp__<plugin name>__<name>`, and the handle's `name` is that full name.
 - `description` tells Claude what the tool does.
-- `inputSchema` is a JSON Schema with `type: 'object'`. It types `execute`'s `input`, so write it inline. CMod checks each call's input against it, draft 2020-12, and denies an input that does not fit with the list of its errors. Its properties cannot be named `tool`, `tool_use_id`, `consent`, or `agentId`, which Claude Code keeps for itself.
+- `inputSchema` is a JSON Schema with `type: 'object'`. It types `execute`'s `input`, so write it inline. cmod checks each call's input against it, draft 2020-12, and denies an input that does not fit with the list of its errors. Its properties cannot be named `tool`, `tool_use_id`, `consent`, or `agentId`, which Claude Code keeps for itself.
 - `execute` returns the result Claude reads. A `string` and an array of content blocks go to Claude as they are. Any other value goes as JSON. `undefined` returns nothing.
 - An input that does not fit the schema is denied with one line per error under a heading, such as `The open_ticket tool input is not valid:` followed by `- #: Instance does not have required property "title".` The text after `- ` is the location in the input, `#` for its root, and the validator's message.
 - An `execute` that throws denies the call with `The <name> tool failed: <error>`.
@@ -147,13 +147,13 @@ export const tickets = defineMod({
 
 ### Command patterns
 
-A `command` pattern is not a glob. CMod splits it into words the way it splits a Bash command, and matches each command of the call:
+A `command` pattern is not a glob. cmod splits it into words the way it splits a Bash command, and matches each command of the call:
 
 - `'*'` alone matches every shell command. A `*` inside a pattern is a plain character.
 - The first word is the program, matched by its name, so `/bin/rm` counts as `rm`.
 - Every other word that does not start with `-` must appear in the command in the pattern's order, and other words may sit between them: `git push` matches `git push origin main`.
 - Every flag, a word that starts with `-`, must appear somewhere in the command, in any order. `--force` also matches `--force=yes`.
-- CMod splits a cluster of short flags into single flags, in the pattern and in the command alike, so `rm -rf` matches `rm -rf`, `rm -fr`, and `rm -r -f`. A letter that takes a value keeps the rest of the cluster as its value. These programs keep their flags as written: `find`, `java`, `javac`, `go`, `gcc`, `g++`, `clang`, `clang++`, `swift`, `swiftc`, `xcodebuild`, `xcrun`, `ffmpeg`, `ffprobe`, `openssl`, `plutil`, `defaults`, `security`, and `codesign`.
+- cmod splits a cluster of short flags into single flags, in the pattern and in the command alike, so `rm -rf` matches `rm -rf`, `rm -fr`, and `rm -r -f`. A letter that takes a value keeps the rest of the cluster as its value. These programs keep their flags as written: `find`, `java`, `javac`, `go`, `gcc`, `g++`, `clang`, `clang++`, `swift`, `swiftc`, `xcodebuild`, `xcrun`, `ffmpeg`, `ffprobe`, `openssl`, `plutil`, `defaults`, `security`, and `codesign`.
 - Words and flags match exactly, letter case included.
 - Each command of a pipeline or a `&&` chain counts, and so does the command a wrapper runs: `sudo rm -rf /` holds the commands `sudo` and `rm -rf /`. The wrappers are `sudo`, `env`, `doas`, `timeout`, `flock`, `stdbuf`, `watch`, `nohup`, `nice`, `time`, `exec`, `command`, and `xargs`.
 
@@ -168,12 +168,13 @@ type Rule<State> = Target & {
 }
 ```
 
-- Before each call, CMod tries every `deny` rule, then every `ask` rule. The first rule that matches decides, and its `reason` goes with the decision. No match leaves the call to Claude Code.
+- Before each call, cmod tries every `deny` rule, then every `ask` rule. The first rule that matches decides, and its `reason` goes with the decision. No match leaves the call to Claude Code.
 - The strictest answer wins: a mod's `ask` or `deny` beats Claude Code's `allow`, and Claude Code's `deny` beats a mod's `ask`.
 - `when` narrows a rule. The rule matches only when `when` resolves true. A `when` that throws makes the rule match, and the reason adds `Its when check failed: <error>`.
-- When CMod cannot read the call or the session, it denies the call with the reason.
-- For a PowerShell command, or a Bash command CMod cannot fully parse, a `command` rule matches when every word of its pattern appears in the command line. A `read` or `write` rule matches when the command line holds the last segment of its pattern, after the last `/`, and only when that segment holds none of `*?[]{}`. So `{ write: 'Domain.md' }` matches such a command that names `Domain.md`, and `{ write: '**/.env*' }` never matches one.
+- When cmod cannot read the call or the session, it denies the call with the reason.
+- For a PowerShell command, or a Bash command cmod cannot fully parse, a `command` rule matches when every word of its pattern appears in the command line. A `read` or `write` rule matches when the command line holds the last segment of its pattern, after the last `/`, and only when that segment holds none of `*?[]{}`. So `{ write: 'Domain.md' }` matches such a command that names `Domain.md`, and `{ write: '**/.env*' }` never matches one.
 - `permissions({})` throws `permissions: give it a deny or an ask rule, or remove it from setup.`
+- A mod that uses `permissions` calls `registerPermissionCheck(addHook)` after `registerMod` in `hooks/register.ts` ([mod.md](mod.md)). Without it the mod does not start.
 
 `when` gets the call, typed by the target's key. `jobs/permissions.js` exports each type:
 
@@ -214,8 +215,8 @@ export const guard = defineMod({
 check<State>(options: { readonly after: Target | Target[]; readonly run: readonly string[]; readonly timeoutMs?: number }): Job<void, State>
 ```
 
-- After each call that matches `after` and succeeds, CMod runs `run`. A call that was denied or failed runs nothing.
-- For a `read` or `write` target, CMod adds the matched files that still exist to the end of `run`, as absolute paths. For any other target it runs `run` as it is.
+- After each call that matches `after` and succeeds, cmod runs `run`. A call that was denied or failed runs nothing.
+- For a `read` or `write` target, cmod adds the matched files that still exist to the end of `run`, as absolute paths. For any other target it runs `run` as it is.
 - A mod installed for the person passes no folder, so Claude Code runs the command in the session's working folder. A project plugin runs it at the root of the work tree that holds the last matched file, or the matched command's folder.
 - A command that exits with another code than 0 adds `<command> exited with <code>:` and its output to the call's result, so Claude reads the failure right after its own call.
 - `timeoutMs` is 60 seconds by default and 10 minutes at most.
@@ -283,7 +284,7 @@ type Usage = { model: string; context: { tokens?: number; window: number; percen
 ```
 
 - `text` returns the status line's text, or `undefined` to clear it.
-- CMod calls `text` when the mod starts, every `interval` milliseconds (10000 by default), and whenever Claude Code measures the session. It sends the text only when it changed.
+- cmod calls `text` when the mod starts, every `interval` milliseconds (10000 by default), and whenever Claude Code measures the session. It sends the text only when it changed.
 - A `text` that throws keeps the last text, and the error goes to Claude Code's debug log.
 - A mod has one status line. A second `statusLine` throws: join the texts in one.
 - An `interval` below 1 throws.
@@ -316,7 +317,7 @@ type Program = {
 - `command` is the program on `PATH` and its arguments. `environment` sets variables for it. An empty `command` throws.
 - The program's first line on standard output must be its address: `127.0.0.1:<port>`, or `unix:<absolute socket path>`. `ready()` then resolves `{ url: 'http://127.0.0.1:<port>' }`, or `{ url: 'http://localhost', socketPath }`. Pass both to `mod.http.fetch`.
 - In an interactive session the program starts with the mod. Otherwise it starts at the first `ready()`.
-- When the program exits, CMod starts it again after 1, 2, 4, 8, and 16 seconds. After 5 failed tries, or a first line that is not an address, the state is `fatal`, `ready()` rejects, and CMod logs `<mod>: the <program> program stopped: <reason>`.
+- When the program exits, cmod starts it again after 1, 2, 4, 8, and 16 seconds. After 5 failed tries, or a first line that is not an address, the state is `fatal`, `ready()` rejects, and cmod logs `<mod>: the <program> program stopped: <reason>`.
 - A program that ships with the mod gets onto `PATH` through the `program` key of the mod's `package.json` ([install-steps.md](install-steps.md)). A program an install step fetched with `cmod download` is not on `PATH`, so `command` names it by its full path, `${mod.dataFolder}/bin/<program>`.
 
 ```ts
@@ -359,12 +360,12 @@ type JobContext<State> = {
 ```
 
 - `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.close`, or `cmod.call`. The handler calls `next(e)` to pass the event on.
-- `announce` adds a phrase to the list CMod logs when the mod first starts.
+- `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.close`, or `cmod.call`. The handler calls `next(e)` to pass the event on. A job with a handler on `tool.check`, `classic.PreToolUse`, or `classic.PermissionRequest` needs `registerPermissionCheck` in `hooks/register.ts` ([mod.md](mod.md)).
+- `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.
-- `toolCalls.cwdOf(toolUseId)` returns the working folder at the call's `PreToolUse`, or `undefined` once its `PostToolUse` or `PostToolUseFailure` has run. CMod keeps the folders of the last 100 calls.
+- `toolCalls.cwdOf(toolUseId)` returns the working folder when the call ran, or `undefined` once its `PostToolUse` or `PostToolUseFailure` has run. cmod keeps the folders of the last 100 calls.
 
 ```ts
 import { defineMod, type Job } from '../node_modules/@cmodjs/core/mod.js'
@@ -412,7 +413,7 @@ Each member calls the member of the same name in Claude Code's hooks API, `$`, w
 | `fs.stat(path, options?)` | Resolves `{ kind, size, mtimeMs, isLink }`, and `realPath` with `{ resolve: true }`. It rejects for a missing path. |
 | `http.fetch(url, init?)` | What `mod.http.fetch` calls. |
 | `settings.read(args?)` | What `mod.settings.read` calls. |
-| `store.get`, `store.set`, `store.delete`, `store.keys` | The plugin's key-value store, where CMod also keeps `mod.state`. |
+| `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() }`. |
 | `clock.every(ms, fn)` | Calls `fn` every `ms` milliseconds, at least 1, and returns `{ cancel() }`. |

package/docs/mod.md

@@ -1,6 +1,6 @@
 # Define a mod
 
-`defineMod` describes a mod: its name, its state, the methods it offers other mods, and the `setup` function that attaches everything to Claude Code. `connect` hands the definition to Claude Code.
+`defineMod` describes a mod: its name, its state, the methods it offers other mods, and the `setup` function that attaches everything to Claude Code. `registerMod` registers the definition with Claude Code.
 
 ## defineMod
 
@@ -17,7 +17,7 @@ type ModDefinition<State, 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 `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 `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.
 - `state` holds the starting values, grouped by how long they last. [state.md](state.md) explains the groups.
 - `api` holds the methods other mods call. [dependencies.md](dependencies.md) explains it.
 - `setup` runs once when the mod starts. It adds hooks, panes, slot renders, and jobs. It may be `async`.
@@ -41,9 +41,9 @@ 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 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.
 
-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`.
+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:
 
@@ -51,28 +51,43 @@ When a step fails, the mod does not start. Its progress line above the prompt na
 - `its state did not load: <error>` when reading the saved values or a `state.json` fails.
 - `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 `PreToolUse` or `PermissionRequest`, or a job that decides permissions, and `register.ts` does not register the permission check.
 
 Each of these says `Fix it, then run /reload-plugins.`
 
-## Connect the mod to Claude Code
+## Register the mod with Claude Code
 
-`hooks/hooks.json` names `hooks/register.ts` as the plugin's hooks module. `register.ts` calls `connect` and does nothing else:
+`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 { connect } from '../node_modules/@cmodjs/core/connect.js'
+import { registerMod } from '../node_modules/@cmodjs/core/register.js'
 import { greeter } from '../src/mod.js'
 
-export function register(on: On): void {
-  connect(on, greeter)
+export function register(addHook: On): void {
+  registerMod(addHook, greeter)
 }
 ```
 
 ```ts
-connect<State>(on: On, definition: ModDefinition<State>): void
+registerMod<State>(addHook: On, definition: ModDefinition<State>): void
+registerPermissionCheck(addHook: On): void
 ```
 
-`connect` registers one handler per Claude Code event the mod can use, and routes each event to the mod. 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. 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.
+`registerMod` registers one handler per Claude Code event the mod can use, and routes each event to the mod. It leaves out Claude Code's permission check, the events `tool.check`, `PreToolUse`, and `PermissionRequest`.
+
+A mod that decides permissions calls `registerPermissionCheck` after `registerMod`. That covers a hook on `PreToolUse` or `PermissionRequest`, the `permissions` job, and a job of your own on `tool.check`:
+
+```ts
+export function register(addHook: On): void {
+  registerMod(addHook, guard)
+  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.
+
+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
 
@@ -100,7 +115,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) |
-| `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) |
+| `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`. | |
 | `on` | Adds a hook on a Claude Code event. | [hooks.md](hooks.md) |
@@ -130,7 +145,7 @@ Both run a program without a shell. `argv[0]` is the program and the rest are it
 - `spawn` streams `{ stream: 'stdout' | 'stderr', text }` pieces as the program writes them. Its `result` resolves `{ code, signal }` once the stream is read to its end. Its first pull rejects when the program cannot start.
 - The `for await` loop over a `spawn` is the program's life. Leaving the loop, or calling `return()` on the stream, kills the program, and so does unloading the mod. Returning from the hook does not.
 
-Inside a job, CMod adds the job's deadline to each call ([jobs.md](jobs.md)).
+Inside a job, cmod adds the job's deadline to each call ([jobs.md](jobs.md)).
 
 ```ts
 import { defineMod } from '../node_modules/@cmodjs/core/mod.js'