@cmodjs/core 0.1.7 → 0.1.9

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.
 
@@ -49,15 +49,15 @@ Runs every check this machine can run on the mod at `path` (default: the current
 2. Checks its layout.
 3. Checks that each step runs a script.
 4. Checks its imports.
-5. Looks for prebuilt binaries.
+5. Looks for prebuilt binaries outside `cli/`.
 6. Validates it with Claude Code, `claude plugin validate --strict`.
-7. Type-checks it with `tsc`. It skips this until `.claude-plugin/types/` exists, which Claude Code writes the first time a session loads the mod: run `cmod link`, start `claude` once, then run `cmod check` again.
+7. Type-checks it with `tsc`. When `.claude-plugin/types/` is missing, as in a fresh clone or in CI, Claude Code writes it first: cmod loads the mod in one `claude -p` run with a config folder of its own and no model to reach, so the run sends nothing.
 8. Lints it with `oxlint`.
 9. Runs, with `bun test`, every test file that does not import `claude-code/testing`.
 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.
 
@@ -87,7 +87,7 @@ Releases the mod at `path` (default: the current folder) at the version in its `
 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

@@ -7,12 +7,29 @@
 ```ts
 mod.on<E extends ModEvent>(event: E, hook: ModHook<E>): void
 
-type ModHook<E> = (input: HookInputs[E]) => HookAnswer | void | Promise<HookAnswer | void>
+type ModHook<E> = (input: HookInput<E>) => HookAnswer | void | Promise<HookAnswer | void>
 ```
 
 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.
+`HookInput<E>`, exported from `mod.js`, is the input a hook on `E` gets, for a hook that lives in a function of its own:
+
+```ts
+import type { HookAnswer, HookInput, Mod } from '../node_modules/@cmodjs/core/mod.js'
+
+export async function addBranch(mod: Mod, input: HookInput<'SessionStart'>): Promise<HookAnswer | undefined> {
+  const { stdout } = await mod.process.run(['git', 'branch', '--show-current'], { cwd: input.cwd })
+  return { hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: `The git branch is ${stdout.trim()}.` } }
+}
+```
+
+A `PreToolUse` hook runs on Claude Code's `tool.call`, before Claude Code checks the call's permission. It rewrites the call's input, adds context to it, or denies it, and Claude Code's permission check sees the rewritten input. A `permissionDecision` of `'allow'` or `'ask'` decides the call's permission, so it takes effect in Claude Code's permission check, and only when the mod's `hooks/register.ts` calls `registerPermissionCheck(addHook)` after `registerMod` ([mod.md](mod.md)):
+
+- `'allow'` runs the call without asking the person, and `'ask'` asks them, with `permissionDecisionReason` as the question's reason.
+- A deny from a settings rule or another hook still denies the call, and the mod's own `permissions` job can still ask or deny.
+- Without `registerPermissionCheck`, an `'allow'` or `'ask'` denies the call with `<mod>: the PreToolUse hook answered permissionDecision "allow", so hooks/register.ts must call registerPermissionCheck(addHook) after registerMod.`
+
+A hook on `PermissionRequest` takes part in that check too, so a mod with one does not start without `registerPermissionCheck`.
 
 ```ts
 import { defineMod } from '../node_modules/@cmodjs/core/mod.js'
@@ -31,7 +48,7 @@ export const safeDelete = defineMod({
 
 ## Every ModEvent
 
-`ModEvent` names the 17 events a mod hooks. The input of each is the hook input a `settings.json` hook reads for that event, typed as `ClassicHookInputs['<event>']` in the `claude-code` module, with the changes this table names.
+`ModEvent` names the 18 events a mod hooks. The input of each is the hook input a `settings.json` hook reads for that event, typed as `ClassicHookInputs['<event>']` in the `claude-code` module, with the changes this table names.
 
 | Event | Input changes |
 | --- | --- |
@@ -39,7 +56,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` |
@@ -52,18 +69,57 @@ export const safeDelete = defineMod({
 | `Stop` | none |
 | `StopFailure` | none |
 | `CwdChanged` | no `transcript_path` |
+| `FileChanged` | none |
+
+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.
+
+Claude Code raises `FileChanged` when a file it watches changes, with the file's `file_path` and `event`: `'change'`, `'add'`, or `'unlink'`. It watches the paths a `SessionStart` hook answers in `watchPaths`:
 
-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.
+```ts
+mod.on('SessionStart', () => ({ hookSpecificOutput: { hookEventName: 'SessionStart', watchPaths: [`${mod.dataFolder}/history`] } }))
+mod.on('FileChanged', ({ file_path, event }) => mod.ui.toast(`${file_path}: ${event}`))
+```
 
 ## 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.
+
+## shell.js and path.js: read a command line
+
+`shell.js` reads a Bash line the way cmod does for `files`, and `path.js` is `node:path`'s POSIX functions, which a mod cannot import from Node:
+
+```ts
+parseShell(line: string): ParsedShell
+
+type ParsedShell = { commands: ShellCommand[]; reads: string[]; writes: string[]; fetches: string[]; isFullyParsed: boolean }
+type ShellCommand = { argv: [string, ...string[]]; folder: string }
+
+resolve(...paths): string   join(...paths): string   dirname(path): string   basename(path, suffix?): string
+extname(path): string        relative(from, to): string   isAbsolute(path): boolean   normalize(path): string
+```
+
+- `commands` lists every command the line runs, those inside `sudo`, `bash -c`, `$(…)`, and heredocs included, with flags such as `-rf` split into `-r` and `-f`.
+- `folder` is where a command runs, as the line wrote it: `''` for the folder the line starts in, `src` after `cd src`, `/tmp` after `cd /tmp`, and `~/p` after `cd ~/p`. `resolve(input.cwd, folder)` makes it absolute.
+- `reads`, `writes`, and `fetches` are the paths and URLs the commands name, as written. A path that holds a shell expansion makes `isFullyParsed` false, and so does a line the parser cannot read.
+- `resolve` has no working folder to start from in Claude Code's hooks, so pass an absolute folder first, such as `resolve(mod.cwd, path)`.
+
+```ts
+import { basename, resolve } from '../node_modules/@cmodjs/core/path.js'
+import { parseShell } from '../node_modules/@cmodjs/core/shell.js'
+
+mod.on('PreToolUse', (input) => {
+  if (input.tool_name !== 'Bash') return
+  for (const { argv, folder } of parseShell(String(input.tool_input['command'])).commands) {
+    if (basename(argv[0]) === 'trace') mod.ui.toast(`trace runs in ${resolve(input.cwd, folder)}`)
+  }
+})
+```
 
 ## HookAnswer: what a hook can answer
 
@@ -99,7 +155,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:
@@ -108,12 +164,12 @@ Each event reads only some `hookSpecificOutput` fields:
 | --- | --- |
 | `SessionStart` | `additionalContext`, `initialUserMessage`, `sessionTitle`, `watchPaths`, `reloadSkills` |
 | `UserPromptSubmit` | `additionalContext`, `sessionTitle`, `suppressOriginalPrompt` |
-| `PreToolUse` | `additionalContext`, `permissionDecision`, `permissionDecisionReason`, `updatedInput` |
+| `PreToolUse` | `additionalContext`, `permissionDecision` (`'allow'` and `'ask'` need `registerPermissionCheck`), `permissionDecisionReason`, `updatedInput` |
 | `PermissionRequest` | `decision` |
 | `PermissionDenied` | `retry` |
 | `PostToolUse` | `additionalContext`, `updatedToolOutput`, `updatedMCPToolOutput` |
 | `PostToolUseFailure`, `PostToolBatch`, `SubagentStart`, `SubagentStop`, `Stop` | `additionalContext` |
-| `SessionEnd`, `InstructionsLoaded`, `Notification`, `PreCompact`, `StopFailure`, `CwdChanged` | none |
+| `SessionEnd`, `InstructionsLoaded`, `Notification`, `PreCompact`, `StopFailure`, `CwdChanged`, `FileChanged` | none |
 
 A field the event does not read is an error: `it answered hookSpecificOutput.<field>, which <event> does not read. Remove it from the answer.` A flag set to `false`, such as `retry: false`, counts as unset.
 
@@ -122,7 +178,7 @@ A field the event does not read is an error: `it answered hookSpecificOutput.<fi
 Every mod's hooks and Claude Code's own `settings.json` hooks answer the same event.
 
 - `additionalContext` from every hook reaches Claude, each in turn.
-- On `PreToolUse` the strictest decision wins: `deny` over `ask` over `allow`. A mod's `allow` never overrides a `deny` from another hook.
+- `PreToolUse` hooks run one inside the next, in the order mods and `mod.on` added them. A deny stops the call there, so no hook after it runs. `updatedInput` replaces the tool's input for every hook after it and for Claude Code. `additionalContext` reaches Claude with the call's result, and not at all when Claude Code refuses the call.
 - For every other field, the mod's answer replaces the answer of the hooks beneath it.
 
 ```ts
@@ -147,11 +203,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:
 
@@ -32,9 +32,9 @@ The template is a working example to replace. It counts the prompts of the sessi
 
 A mod imports `@cmodjs/core` by path, such as `../node_modules/@cmodjs/core/mod.js`, because Claude Code loads a plugin's own files only. Types such as `RenderElement` and `On` come from the `claude-code` module.
 
-## Type-check after the first session
+## Claude Code's types
 
-Claude Code writes `.claude-plugin/types/` the first time a session loads the mod. That folder holds the `tsconfig.json` the mod's own extends, the `claude-code` module, and the `h` JSX global. Until it exists, `tsc` fails, and `cmod check` skips its type check. Run `cmod link`, start `claude` once, then type-check. A project plugin needs no link: start `claude` in its repository and trust it.
+`.claude-plugin/types/` holds the `tsconfig.json` the mod's own extends, the `claude-code` module, and the `h` JSX global. Claude Code writes it when it loads the mod, and git ignores it. `cmod check` has Claude Code write it when it is missing, so a fresh clone and CI type-check too. Until it exists, `tsc` alone fails, so run `cmod check` once first.
 
 ## Where a mod runs
 
@@ -72,9 +72,11 @@ A mod imports from the files below, and every other file in this package is inte
 | --- | --- | --- |
 | `mod.js` | `defineMod`, `ModDefinition`, `Mod`, `JobContext`, `Job`, `ProgressStep`, `PaneHandle`, `longestMs`, `messageOf` | [mod.md](mod.md), [jobs.md](jobs.md), [ui.md](ui.md) |
 | `mod.js` | `Claude`, `RoutedEvent`, `RoutedHook`, `ToolCalls` | [jobs.md](jobs.md) |
-| `mod.js` | `ModEvent`, `ModHook`, `HookAnswer` | [hooks.md](hooks.md) |
+| `mod.js` | `ModEvent`, `ModHook`, `HookInput`, `HookAnswer` | [hooks.md](hooks.md) |
 | `mod.js` | `notInstalled` | [dependencies.md](dependencies.md) |
 | `register.js` | `registerMod`, `registerPermissionCheck` | [mod.md](mod.md) |
+| `shell.js` | `parseShell`, `ParsedShell`, `ShellCommand` | [hooks.md](hooks.md) |
+| `path.js` | `resolve`, `join`, `dirname`, `basename`, `extname`, `relative`, `isAbsolute`, `normalize` | [hooks.md](hooks.md) |
 | `testing.js` | `testMod`, `TestOptions`, `TestInput`, `TestedMod`, `Fakes`, `Shown`, `TestCall` | [testing.md](testing.md) |
 | `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) |
@@ -98,4 +100,4 @@ A mod imports from the files below, and every other file in this package is inte
 
 ## Check your work
 
-Run `cmod check` in the mod's folder. It installs the packages, checks the layout and the imports, validates the mod with Claude Code, type-checks it once `.claude-plugin/types/` exists, lints it, and runs its tests. Each failure names its fix. [commands.md](commands.md) lists every step.
+Run `cmod check` in the mod's folder. It installs the packages, checks the layout and the imports, validates the mod with Claude Code, type-checks it, lints it, and runs its tests. Each failure names its fix. [commands.md](commands.md) lists every step.

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:
 
@@ -134,9 +134,9 @@ A mod that builds its own command-line program keeps its source in `cli/`, and C
    }
    ```
 
-   The program's name is the one `bin` command, or else `name`. A Rust program declares the same keys under `[package.metadata.cmod]` in `cli/Cargo.toml`.
+   The program's name is the one `bin` command, or else `name`. A Rust program declares the same keys under `[package.metadata.cmod]` in `cli/Cargo.toml`, and its name is the one `[[bin]]` `name`, or else the `[package]` `name`.
 
-2. The build writes one file per machine into `output`, each named `<program>-<os>-<arch>`, such as `hello-darwin-arm64`.
+2. The build writes one file per machine into `output`, each named `<program>-<os>-<arch>`, such as `hello-darwin-arm64`. cmod runs it with `CMOD_MACHINES` set to the machines it needs, separated by spaces: `cmod link` names this machine alone, and `cmod publish` names all four. A build that ignores `CMOD_MACHINES` and builds every machine works too, only slower to link. cmod takes only the files the build wrote in that run, so a build left from an earlier run is never released.
 
 3. The mod's own `package.json` names the program: `"cmod": { "program": "hello" }`. `.claude-plugin/plugin.json` names the GitHub `repository`.
 
@@ -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` finds in a folder ahead of `~/.local/bin`.
 - `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,11 +168,11 @@ 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.
 
@@ -215,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.
@@ -284,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.
@@ -317,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
@@ -360,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. 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.
+- `claude.store` is where cmod saves `mod.state`, under keys that start with `<mod>.`, such as `<mod>.<key>`. A job of your own never writes those keys, or it changes the mod's state behind cmod's back.
+- `on` adds a Claude Code hook-module handler, `(e, next) => …`, on a `classic.<ModEvent>` event or on `tool.check`, `tool.call`, `prompt.submit`, `prompt.context`, `command.run`, `session.measure`, `skill.prompt`, `ui.render`, `ui.press`, `ui.scroll`, `ui.close`, or `cmod.call`. The handler calls `next(e)` to pass the event on. A job with a handler on `tool.check` or `classic.PermissionRequest` needs `registerPermissionCheck` in `hooks/register.ts` ([mod.md](mod.md)).
+- `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 when the call ran, 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'
@@ -405,15 +405,14 @@ Each member calls the member of the same name in Claude Code's hooks API, `$`, w
 | `ui.open(pane)` | Opens a pane, `{ id, title?, focus?, closeOnEscape?, holdToasts?, rows?, columns? }`, and resolves `{ isPlaced }`. |
 | `ui.close(pane)` | Closes the open pane with that `{ id }`. |
 | `ui.panes()` | The plugin's open panes: each one's id, title, and whether it is shown, holds the keyboard, and is placed. |
+| `ui.scroll(args)` | What `mod.ui.scroll` calls. |
 | `ui.resolve(e)` | The element table of the surface a `ui.render` event draws on. |
 | `process.run(argv, init?)` | Runs a program to its end. `mod.process.run` is built on it. |
 | `process.spawn(request)` | Starts a program and streams its output. `mod.process.spawn` is built on it. |
-| `fs.read`, `fs.write`, `fs.list` | What `mod.fs` calls. A relative path is under the session's working folder. |
-| `fs.exists(path)` | Resolves whether the path exists. |
-| `fs.stat(path, options?)` | Resolves `{ kind, size, mtimeMs, isLink }`, and `realPath` with `{ resolve: true }`. It rejects for a missing path. |
+| `fs.read`, `fs.write`, `fs.list`, `fs.exists`, `fs.stat` | What `mod.fs` calls. A relative path is under the session's working folder. |
 | `http.fetch(url, init?)` | What `mod.http.fetch` calls. |
 | `settings.read(args?)` | What `mod.settings.read` calls. |
-| `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() }`. |
@@ -423,9 +422,11 @@ Each member calls the member of the same name in Claude Code's hooks API, `$`, w
 | `session.model()` | The main conversation's model, as `/model` shows it. |
 | `session.usage()` | When the session began, the context window's fill, the rate-limit windows, and the cost, as the status line has them. |
 | `session.surfaces()` | Every surface the session draws on, `terminal` first. Empty in a plain `-p` run. |
+| `session.messages(args?)` | What `mod.session.messages` calls. |
 | `command.register(spec)` | Adds a slash command. `slashCommand` is built on it. |
 | `tool.register(spec)` | Adds a tool. `tool` is built on it. |
 | `agent.list()` | The session's subagents and teammates so far. |
+| `agent.spawn(args)` | What `mod.agent.spawn` calls. |
 | `env.home()` | The `HOME` variable, or `undefined` when it is unset. |
 | `env.dataHome()` | The `XDG_DATA_HOME` variable, or `undefined`. |
 | `env.configHome()` | The `CLAUDE_CONFIG_DIR` variable, or `undefined`. |