@cmodjs/core 1.0.0 → 1.5.0

package/docs/commands.md

@@ -98,7 +98,7 @@ Releases the mod at `path` (default: the current folder) at the version in its `
 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. The cmod entry points at the `release` branch of `heyJordanParker/cmod`, so the mod's `"cmod"` dependency resolves in this marketplace and follows each cmod release with no new publish of the mod.
-7. Commits that file, tags `v<version>`, pushes the tag and the `release` branch, and creates the GitHub release. Its notes are the version's section of the committed `CHANGELOG.md`, above GitHub's compare link ([mod.md](mod.md#release-notes)). `--dry-run` prints them.
+7. Commits that file, tags `v<version>`, pushes the tag and the `release` branch, creates the GitHub release with every file, then pushes the branch that holds `marketplace.json`. So Claude Code never updates anyone to a release whose files are not up yet. Its notes are the version's section of the committed `CHANGELOG.md`, above GitHub's compare link ([mod.md](mod.md#release-notes)). `--dry-run` prints them.
 8. Prints the link to paste as the Repository when you submit the mod at [claude.ai/directory/manage](https://claude.ai/directory/manage), such as `https://github.com/owner/greeter/tree/release`. The portal reads the branch from the link, so the directory follows `release`.
 
 The release keeps `package.json`, so Claude Code still installs the mod's packages for its install and uninstall steps. It keeps `bun.lock` too, unless a `"files"` list leaves it out. `main` keeps the source only.
@@ -179,30 +179,33 @@ Lists every plugin Claude Code has installed or linked, with its version. A mod
 
 ```text
 cmod history sessions [--all] [--since 2d] [--running] [--project <folder>] [--json]
-cmod history search <text> [--all] [--since 2d] [--running] [--project <folder>] [--limit <n>] [--before <session>:<id>] [--json]
+cmod history search <text> [--all] [--since 2d] [--running] [--project <folder>] [--session <id> [--task <id>] [--turn <id>] [--context <n>] [--goal]] [--limit <n>] [--before <session>:<id>] [--json]
 cmod history messages [<session>] [--task <id>] [--turn <id>] [--after <id>] [--last <n>] [--json]
-cmod history turns [<session>] [--context <n>] [--last <n>] [--json]
-cmod history contexts [<session>] [--json]
-cmod history tasks [<session>] [--task <id>] [--json]
-cmod history goal [<session>] [--json]
+cmod history turns [<session>] [--task <id>] [--context <n>] [--last <n>] [--json]
+cmod history contexts [<session>] [--task <id>] [--json]
+cmod history tasks [<session>] [--task <id> | --nested] [--json]
+cmod history goal [<session>] [--task <id>] [--json]
+cmod history usage [<session>] [--task <id>] [--json]
 cmod history state [<session>] [--json]
-cmod history follow <session>... [--json]
+cmod history follow [<session>...] [--running] [--json]
 cmod history index
 ```
 
 Reads every conversation Claude Code saved, as the sessions, contexts, turns, tasks, and messages `sessions` answers a mod ([session.md](session.md)), so a person or an agent reads them in a terminal without parsing a transcript.
 
 - `sessions` lists the conversations of the current folder's project, or `--project`'s, newest first, each with its time, id, and title. `--all` lists every project's, `--since` keeps those active in the last `30m`, `6h`, `2d`, or `1w`, or since a date such as `2026-10-01`, and `--running` keeps those open in Claude Code now.
-- `search` prints the newest 50 messages whose text or tool input contains the text, at least 3 characters, any case, each with its time and session. Each tool input value is searched in its first 1,024 characters, and tool results are not searched. `--all`, `--since`, and `--running` scope it as they scope `sessions`, `--limit` changes the 50, and `--before <session>:<id>` prints the page after the message it names, the last one of the page before.
+- `search` prints the newest 50 messages whose text or tool input contains the text, at least 3 characters, any case, each with its time and session. Each tool input value is searched in its first 1,024 characters, and tool results are not searched. `--all`, `--since`, and `--running` scope it as they scope `sessions`, `--limit` changes the 50, and `--before <session>:<id>` prints the page after the message it names, the last one of the page before. `--session` searches one conversation, and inside it `--task` searches a task and the tasks it started, `--turn` one turn, `--context` one context, and `--goal` the tasks of the conversation or of `--task`.
 - `messages` prints one conversation's messages in order: the session named, or the one the command runs in when Claude Code runs it. `--task` reads a task's messages instead, `--turn` keeps one turn's, `--after` starts after a message id, and `--last` keeps that many from the end.
 - `turns` prints the conversation's turns, each opened by a prompt and closed when Claude finishes. `--context` keeps one context's, and `--last` keeps that many from the end.
 - `contexts` prints the conversation's contexts, a new one after each compaction.
-- `tasks` prints the tasks the conversation started, or with `--task` the tasks that task started.
+- `tasks` prints the tasks the conversation started, with `--task` the tasks that task started, and with `--nested` every task at any depth.
 - `goal` prints what the conversation is for: the goal a mod set, or its first prompt.
+- `usage` prints the model and the context's tokens as of the last reply.
+- `--task` reads `turns`, `contexts`, `goal`, and `usage` of the session a task's owner runs, the way they read the conversation's.
 - `state` prints what a running conversation resumes from.
-- `follow` prints each message, turn, context, task, and goal change of the sessions named as Claude Code saves it, until stopped with Ctrl+C. The cmod plugin runs it to hear other running sessions.
+- `follow` prints each message, turn, context, task, and goal change of the sessions named as Claude Code saves it, until stopped with Ctrl+C. `--running` follows every running session of the project too, and each one that starts later. The cmod plugin runs it to hear other running sessions.
 - `--json` prints JSON instead of one line each.
-- `index` reads every saved conversation into the index at `~/.local/share/cmod/history-3.sqlite`, which holds where each message is in its transcript, not a copy of it, and each conversation's turns, contexts, and tasks. While a mod other than cmod holds the `conversation` permission, the cmod plugin runs it in the background at each session's start, and a second run while one is running exits at once. The index forgets a conversation whose transcript is deleted.
+- `index` reads every saved conversation into the index at `~/.local/share/cmod/history-5.sqlite`, which holds where each message is in its transcript, not a copy of it, and each conversation's turns, contexts, and tasks. While a mod other than cmod holds the `conversation` permission, the cmod plugin runs it in the background at each session's start, and a second run while one is running exits at once. The index forgets a conversation whose transcript is deleted.
 
 ## Run in an install script
 
@@ -250,6 +253,14 @@ cmod settings <mod> <user|project|local> <json> [--project <folder>]
 
 Changes Claude Code settings for a set-up mod, as its `settings.user.update`, `settings.project.update`, and `settings.local.update` do ([mod.md](mod.md#settings-claude-code-s-settings-files)), such as `cmod settings keeper user '{"cleanupPeriodDays":365}'`. It writes each top-level key of the JSON object into the user, project, or local settings, and `null` removes the key. The project and local settings are those of `--project`, the current folder when it is left out, and `mcpServers` in the project settings goes to `.mcp.json`. Each key needs the mod's `config` permission for it. cmod keeps every other key and the file's formatting, and `cmod teardown` takes out each value the mod set that is still the same.
 
+### cmod rules
+
+```text
+cmod rules [--project <folder>] [--json]
+```
+
+Links the `rules/` folder of each mod that is on and has the `prompt` permission into Claude Code's rules folder, and removes the link of each that is off, lacks the permission, or is removed ([mod.md](mod.md#rules)). A mod the person installed links at `<config>/rules/<mod>`, and one turned on only for `--project`, the current folder when it is left out, links at `<project>/.claude/rules/<mod>`. It prints the rules it linked. With `--json` it prints `{ linked, placed, removed }`, where `placed` and `removed` name the mods whose link this run made or took away. `cmod install`, `update`, `remove`, `enable`, `disable`, `permission`, `setup`, `teardown`, `link`, and `unlink` run it after they succeed, and the cmod plugin runs it at each session's start and each prompt.
+
 ### cmod option
 
 ```text

package/docs/dependencies.md

@@ -88,13 +88,15 @@ export const outline = defineMod({
 A call that cannot answer rejects with one of these reasons:
 
 ```text
-tracer is not installed. Run cmod install tracer.
+tracer is not installed. Add it with /plugin.
+tracer is not set up. Its toast says why.
 tracer is installing. Try again when it's ready.
 tracer has no method signatures.
 tracer: <the message of the error the method threw>
 ```
 
-- `tracer is not installed` covers a provider whose code did not load, one the person declined to install, and one whose install failed.
+- `tracer is not installed` covers a provider whose code did not load.
+- `tracer is not set up` covers a provider the person declined to install and one whose install failed. Its own toast shows why, with `Retry` or `Install`.
 - `tracer is installing` covers a provider that is still running its install step. A provider that is only starting makes the call wait for it, up to 9 seconds.
 - When tracer is disabled, Claude Code unloads the mod that lists it, with its own error: `Dependency "tracer" is disabled — enable it or remove the dependency`.
 - A call fails with `mod.dependencies.tracer.signatures passed its 30 s deadline` when the other mod takes longer than 30 seconds. A job bounds the whole function that makes the call by its own deadline ([jobs.md](jobs.md)), so a slow call inside `slashCommand` can fail the command first, with `/outline passed the 30 s deadline of slashCommand`.
@@ -103,11 +105,11 @@ tracer: <the message of the error the method threw>
 notInstalled(name: string): string
 ```
 
-`notInstalled`, exported from `mod.js`, returns the first reason for a mod name: `<name> is not installed. Run cmod install <name>.` A test uses it to expect that message.
+`notInstalled`, exported from `mod.js`, returns the first reason for a mod name: `<name> is not installed. Add it with /plugin.` A test uses it to expect that message.
 
 ## Test the calls
 
-`testMod(outline, { dependencies: { tracer: { signatures: async () => [] } } })` answers tracer's methods with the functions given. A call to a mod the test does not fake fails with `tracer is not installed. Run cmod install tracer.`, as in Claude Code. [testing.md](testing.md) covers it.
+`testMod(outline, { dependencies: { tracer: { signatures: async () => [] } } })` answers tracer's methods with the functions given. A call to a mod the test does not fake fails with `tracer is not installed. Add it with /plugin.`, as in Claude Code. [testing.md](testing.md) covers it.
 
 A test of the provider's own `api` fires `cmod.call`, as a caller's `mod.dependencies` does. The answer is `{ value }` with what the method returned, or `{ deny }` with the reason it failed:
 

package/docs/hooks.md

@@ -67,28 +67,45 @@ export const safeDelete = defineMod({
 
 ## Every hook
 
-`Hook` names the 18 hooks a mod listens to. The input of each is the input a `settings.json` hook reads, typed as `ClassicHookInputs['<hook>']` in the `claude-code` module, with the changes this table names.
+`Hook` names the 33 hooks a mod listens to, every hook Claude Code has. The input of each is the input a `settings.json` hook reads, typed as `ClassicHookInputs['<hook>']` in the `claude-code` module, with the changes this table names.
 
 | Hook | Input changes |
 | --- | --- |
+| `Setup` | none |
 | `SessionStart` | none |
 | `SessionEnd` | none |
 | `UserPromptSubmit` | none |
+| `UserPromptExpansion` | none |
 | `InstructionsLoaded` | none |
+| `ConfigChange` | none |
+| `DirectoryAdded` | none |
+| `PreModelSwitch` | none |
+| `PostModelSwitch` | 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`. |
 | `PermissionRequest` | none |
 | `PermissionDenied` | none |
 | `PostToolUse` | adds `files` |
 | `PostToolUseFailure` | adds `files` |
 | `PostToolBatch` | none |
+| `MessageDisplay` | none |
 | `SubagentStart` | none |
 | `SubagentStop` | none |
+| `TodoCreated` | none |
+| `TodoCompleted` | none |
+| `TeammateIdle` | none |
+| `Elicitation` | none |
+| `ElicitationResult` | none |
 | `Notification` | none |
 | `PreCompact` | none |
+| `PostCompact` | none |
 | `Stop` | none |
 | `StopFailure` | none |
 | `CwdChanged` | no `transcript_path` |
 | `FileChanged` | none |
+| `WorktreeCreate` | none |
+| `WorktreeRemove` | none |
+
+`TodoCreated` and `TodoCompleted` are Claude Code's `TaskCreated` and `TaskCompleted` hooks, under names that say what they hear: an item added to or checked off Claude Code's todo checklist, which its `TaskCreate`, `TaskUpdate`, and `TaskList` tools keep. A cmod `Task` is work handed to another session ([session.md](session.md#turn-context-goal-and-task)), and these hooks never hear one.
 
 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. `sessions.current.cwd` and `sessions.current.project` already hold the new folder when the listener runs.
 
@@ -170,6 +187,8 @@ type HookAnswer = {
     updatedToolOutput?: unknown
     updatedMCPToolOutput?: unknown
     retry?: boolean
+    displayContent?: string
+    worktreePath?: string
   }
 }
 ```
@@ -186,12 +205,16 @@ Each event reads only some `hookSpecificOutput` fields:
 | --- | --- |
 | `SessionStart` | `additionalContext`, `initialUserMessage`, `sessionTitle`, `watchPaths`, `reloadSkills` |
 | `UserPromptSubmit` | `additionalContext`, `sessionTitle`, `suppressOriginalPrompt` |
+| `UserPromptExpansion` | `additionalContext`, `suppressOriginalPrompt` |
+| `PreModelSwitch` | `permissionDecision`, `permissionDecisionReason` |
 | `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`, `FileChanged` | none |
+| `MessageDisplay` | `displayContent`: the text the person sees in place of the message |
+| `WorktreeCreate` | `worktreePath`: the worktree the hook made, in place of Claude Code's own |
+| `Setup`, `PostModelSwitch`, `PostToolUseFailure`, `PostToolBatch`, `SubagentStart`, `SubagentStop`, `Stop` | `additionalContext` |
+| `SessionEnd`, `InstructionsLoaded`, `ConfigChange`, `DirectoryAdded`, `TodoCreated`, `TodoCompleted`, `TeammateIdle`, `Elicitation`, `ElicitationResult`, `Notification`, `PreCompact`, `PostCompact`, `StopFailure`, `CwdChanged`, `FileChanged`, `WorktreeRemove` | 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.
 

package/docs/index.md

@@ -85,7 +85,7 @@ A mod imports from the files below, and every other file in this package is inte
 | `mod.js` | `sessions`, `Sessions`, `Session`, `SessionScope`, `SessionSend`, `SessionEvent`, `SessionPayload`, `TaskStartArgs`, `Usage`, `Matcher` | [session.md](session.md) |
 | `mod.js` | `Message`, `MessageType`, `Prompt`, `Note`, `Reply`, `ToolCall`, `ToolResult`, `Skill`, `Document`, `Notice`, `Sender`, `SenderType`, `Person`, `Schedule`, `Channel`, `Sdk` | [session.md](session.md#message) |
 | `mod.js` | `Context`, `ContextStart`, `ContextEnd`, `Turn`, `TurnStart`, `TurnEnd`, `Goal`, `GoalChange`, `Task`, `TaskStart`, `TaskEnd` | [session.md](session.md#turn-context-goal-and-task) |
-| `mod.js` | `Hook`, `HookInput`, `HookListener`, `HookOptions`, `HookAnswer`, and one constant per hook, from `SessionStart` to `FileChanged` | [hooks.md](hooks.md) |
+| `mod.js` | `Hook`, `HookInput`, `HookListener`, `HookOptions`, `HookAnswer`, and one constant for each of Claude Code's 33 hooks | [hooks.md](hooks.md) |
 | `mod.js` | `Toast`, `ToastId`, `ToastType`, `ToastOptions` | [ui.md](ui.md#toasts) |
 | `mod.js` | `Place`, `PlaceProps`, `ToolGroup`, `ToolProgress`, `CommandOutput`, `AskUserQuestion`, `Spinner`, `TurnDuration`, `SessionMode`, `PromptHint`, `AbovePrompt` | [ui.md](ui.md#places-change-a-row-claude-code-draws) |
 | `mod.js` | `notInstalled` | [dependencies.md](dependencies.md) |

package/docs/install-steps.md

@@ -37,9 +37,9 @@ cmod refuses a `cmod` key that breaks these rules, with the fix in the message:
 Before a step runs for the first time, cmod shows the person the commands, the keys, and the permissions, and asks to run them. cmod hashes the commands, the keys, the permissions, and every file in each script folder, and remembers the hash the person approved with each permission. A change to any of those asks again, and an added permission is the only one it asks about ([permissions.md](permissions.md)).
 
 - In Claude Code, the mod opens the installer pane, `Install <mod>`, focused. It lists `<mod> wants to:`, each permission as one sentence, then `and change your computer:` with `Run <install> now, and <uninstall> when you remove it` and `Bind shift+tab to /mode`, naming only what the mod has. `Accept` (a) runs the setup, and a loading toast above the prompt shows the install with a progress bar. `Not now` (n) and Escape decline.
-- In a session with no screen, such as `claude -p`, the mod waits and logs `<mod> waits for consent to run <install>. Run cmod install <mod> in a terminal.`
+- In a 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.` That person is already in a terminal.
 - In a terminal, `cmod install`, `cmod link`, `cmod try`, and `cmod update` print the commands, the program, the keys, and the permissions, and ask `Set up <mod>? [y/N]`. `--yes` approves without asking.
-- `Not now` leaves the mod off and logs `<mod> is not installed. Run cmod install <mod> to install it.`
+- `Not now` leaves the mod off with the toast `Not installed` and an `Install` button that asks again.
 
 The mod starts only once its install step has run ([mod.md](mod.md)).
 
@@ -117,7 +117,9 @@ The install step runs again on every new version of the mod and whenever its scr
 
 - 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 as an error toast with `Fix the cause, then retry, or run cmod install <mod> in a terminal.` and a `Retry` button that runs the install again.
+- The failure shows at once as an error toast with `Retry`, `Report`, and `Hide` ([ui.md](ui.md#toasts)).
+- When waiting can fix the failure, cmod also retries in the background after 2, 4, 8, 16, 32, 64, and 128 seconds, then every 128 seconds, and the toast says `Trying again in <n> s.` A try that works replaces the toast with `Installed`. Waiting can fix two failures: a linked checkout whose build or install step failed, which cmod tries again once the checkout changed, and a release download that got 404 or no answer, as when a release was published seconds ago. Any other failure waits for `Retry`.
+- Before each try, cmod reads the mod's install record, so a mod another session installed starts without running its install again.
 
 ## The uninstall step
 

package/docs/mod.md

@@ -49,7 +49,7 @@ Claude Code loads the mod at the start of each session. cmod then checks that th
 
 The first time a mod starts on a machine, cmod shows the toast `Installed` under its name. Opened, it lists the mod's `plugin.json` `description`, what setup added, such as `Adds the my-mod pane, a render of AbovePrompt and a hook on UserPromptSubmit.`, what its install step set up, and each permission the person allowed, with a Settings button for `/mods <name>`. The first time a new version starts, the toast is `Updated to <version>`: the first three changes of that version's `CHANGELOG.md` section, the version the machine ran before, and a Changelog button ([Release notes](#release-notes)). A mod with no changelog lists what it adds now and no longer adds instead. A new session, `/reload-plugins`, and a version the machine already ran show no toast.
 
-When a step fails, or the person declines the install, the mod stays stopped. Once `cmod install <name>` sets it up in a terminal, the mod starts at the next prompt of every session it stopped in, with no `/reload-plugins`.
+When a step fails, or the person declines the install, the mod stays stopped. Once another session sets it up, the mod starts at the next prompt of every session it stopped in, with no `/reload-plugins`.
 
 When a step fails, the mod does not start. An error toast above the prompt names the failure, with the fix under it:
 
@@ -61,7 +61,24 @@ When a step fails, the mod does not start. An error toast above the prompt names
 - `the details of its session did not load: <error>` when Claude Code cannot name the session's id, model, or start time.
 - `it decides permissions on <events>, so hooks/register.ts must call registerPermissionCheck(addHook) after registerMod` when `setup` adds a hook on `PermissionRequest`, or a job that decides permissions, and `register.ts` does not register the permission check.
 
-Each of these says `Fix it, then run /reload-plugins.`
+Each of these has `Retry`, which starts the mod again, and `Report` and `Hide` ([ui.md](ui.md#toasts)).
+
+## Rules
+
+A mod's `rules/` folder holds rules in Claude Code's own rule format: one Markdown file per rule, with an optional `paths` list in its front matter. A rule without `paths` applies to every conversation, and a rule with `paths` applies when Claude reads a matching file.
+
+```
+my-mod/
+└── rules/
+    ├── tests.md        <- applies to every conversation
+    └── sql.md          <- front matter paths: ["**/*.sql"]
+```
+
+While the mod is on and has the `prompt` permission, cmod links the folder into Claude Code's rules folder: a mod the person installed links at `<config>/rules/<mod>`, and a mod turned on for one project at `<project>/.claude/rules/<mod>`. A mod turned off for one project keeps its rules out of that project through `claudeMdExcludes` in the project's `.claude/settings.local.json`. A rule the person excluded with `claudeMdExcludes` stays out of the notes too. Turning the mod off, turning `prompt` off, and removing the mod remove the link, and an update links the new version's folder. cmod changes only the links and exclusions it made.
+
+Claude Code reads rules without `paths` only as a session starts. So when cmod links a mod's rules into a running session, it adds them to the conversation as one note, and when it removes the link, one note says the mod's rules no longer apply. A rule taken out of the folder is withdrawn by a note too. When an update changes a rule without `paths`, one note gives its new text. Claude Code loads rules with `paths` itself, at the read that matches.
+
+The `Installed` toast lists the rules, as in `Adds 2 rules: sql and tests.` `cmod check` fails a mod with a `rules/` folder whose `package.json` `"cmod"` does not ask for `"prompt": true`.
 
 ## Release notes
 
@@ -235,6 +252,7 @@ mod.use(slashCommand({ name: 'ci-runs', description: 'Show the CI runs', reply:
 ## settings: Claude Code's settings files
 
 ```ts
+settings.list(): Promise<Setting[]>
 settings.user.read(): Promise<Settings>
 settings.user.update(values: Readonly<Record<string, unknown>>): Promise<void>
 settings.project.read(): Promise<Settings>
@@ -243,6 +261,14 @@ settings.local.read(): Promise<Settings>
 settings.local.update(values: Readonly<Record<string, unknown>>): Promise<void>
 ```
 
+`settings.list` answers every row of Claude Code's `/config` menu, its own and each plugin's, with the value each holds now:
+
+```ts
+type Setting = { key: string; label: string; description?: string; kind: 'boolean' | 'choice' | 'text' | 'number'; value: boolean | string | number | readonly string[]; options?: readonly string[]; plugin?: string; isLocked: boolean }
+```
+
+`plugin` names the plugin a row belongs to, and Claude Code's own rows have none. `isLocked` is true when a managed setting or the organization's policy holds the value.
+
 `settings.user` is the person's own `~/.claude/settings.json`, `settings.project` is the project's `.claude/settings.json`, and `settings.local` is the project's `.claude/settings.local.json`.
 
 - `read` answers the values in that one file, such as `(await settings.user.read())['enabledPlugins']`.
@@ -326,7 +352,7 @@ type Entry = { name: string; isFile: boolean; isFolder: boolean; isLink: boolean
 type Stat = { isFile: boolean; isFolder: boolean; isLink: boolean; size: number; modifiedAt: number; realPath?: string }
 ```
 
-- A relative path is under the session's working folder. An absolute path is used as given. `~/.claude` is Claude Code's config folder, and `~` is the home folder. Text is UTF-8.
+- A relative path is under the session's working folder. An absolute path is used as given. `~/.claude` and `$CLAUDE_CONFIG_DIR` are Claude Code's config folder, and `~` and `$HOME` are the home folder. Text is UTF-8.
 - `read` rejects a missing file and a file over 4 MiB.
 - `write` writes the whole file and creates its folders. Writing outside the project and the mod's data folder needs the `files` permission.
 - `list` lists a folder, the working folder without a path. A symbolic link is neither a file nor a folder, with `isLink` true. `modifiedAt` is the time it last changed, in milliseconds since 1970.

package/docs/permissions.md

@@ -19,11 +19,11 @@ They sit in the `package.json` `cmod` key, beside `install` and `keys`, because
 | `"network": ["api.github.com"]` | Connect to api.github.com | `http.fetch` to that host. A path starting with `/` or `~/` names a socket, such as `"~/.docker/run/docker.sock"`. The address of the mod's own running `program` job needs none |
 | `"run": ["gh"]`, or `"run": "*"` | Run gh on your computer | `process.run`, `process.spawn`, and the `program` and `check` jobs. A program matches by its file name, so `"mermaid-ascii"` covers `${mod.dataFolder}/bin/mermaid-ascii` and the copy in cmod's programs folder |
 | `"files": ["~/.zshrc"]` | Change ~/.zshrc | `fs.write` and `metadata.update` outside the project and the mod's data folder. A folder covers every file below it |
-| `"conversation": true` | Read your Claude Code conversations | Reading `sessions`: their messages, turns, contexts, goals, and tasks, `sessions.list`, `sessions.search`, and a session's `on`. Also reading Claude Code's transcript files |
-| `"prompt": true` | Add text Claude reads and start turns | A session's `send`, the `prompt` and `schedule` jobs, and the hook answers listed below |
+| `"conversation": true` | Read your Claude Code conversations | Reading `sessions`: their messages, turns, contexts, goals, and tasks, `sessions.list`, `search`, `on`, `before`, `usage`, and `clients`. Also reading Claude Code's transcript files |
+| `"prompt": true` | Add text Claude reads and start turns | A session's `send`, a `before` answer that changes or refuses text, the mod's `rules/`, the `prompt` and `schedule` jobs, and the hook answers listed below |
 | `"model": true` | Ask a model, which uses your plan | `model.complete` |
-| `"tasks": true` | Start tasks that work beside Claude | `sessions.current.startTask` |
-| `"tools": true` | Use and change Claude's tool calls | A listener or a job that changes a tool call's input |
+| `"tasks": true` | Start tasks that work beside Claude | A session's `startTask`, and a `before(TaskStart)` or `before(TaskEnd)` answer |
+| `"tools": true` | Use and change Claude's tool calls | A session's `callTool`, a `before(ToolCall)` answer, and a listener or a job that changes a tool call's input |
 | `"config": ["cleanupPeriodDays"]` | Change cleanupPeriodDays in your Claude Code settings | `settings.user.update`, `settings.project.update`, and `settings.local.update` of that setting. `mcpServers` covers the project's `.mcp.json` |
 | `"approve": true` | Approve Claude's tool calls for you | an allow or an ask from the mod's permission rules or hooks, and a `retry`. A deny needs no permission |