@cmodjs/core 0.3.0 → 1.0.0

package/docs/permissions.md

@@ -1,6 +1,6 @@
 # Permissions
 
-A mod declares what it does beyond drawing and answering hooks: the hosts it connects to, the programs it runs, the files it changes outside its project, and whether it reads the conversation, adds text Claude reads, asks a model, starts agents, uses Claude's tools, changes Claude Code's settings, or approves tool calls. The person sees each permission as one sentence when they install the mod, turns each one on or off in `/mods`, and cmod checks every call and every answer against what they granted.
+A mod declares what it does beyond drawing and answering hooks: the hosts it connects to, the programs it runs, the files it changes outside its project, and whether it reads the conversation, adds text Claude reads, asks a model, starts tasks, uses Claude's tools, changes Claude Code's settings, or approves tool calls. The person sees each permission as one sentence when they install the mod, turns each one on or off in `/mods`, and cmod checks every call and every answer against what they granted.
 
 Permissions bind every mod built on `@cmodjs/core`, and the plugin directory reads them from `package.json`. They are a contract, not a sandbox: a Claude Code plugin can skip cmod and call Claude Code directly.
 
@@ -16,18 +16,18 @@ They sit in the `package.json` `cmod` key, beside `install` and `keys`, because
 
 | Permission | The person reads | cmod checks |
 | --- | --- | --- |
-| `"network": ["api.github.com"]` | Connect to api.github.com | `mod.http.fetch` to that host. A path starting with `/` or `~/` names a socket, such as `"~/.docker/run/docker.sock"` |
-| `"run": ["gh"]`, or `"run": "*"` | Run gh on your computer | `mod.process.run`, `mod.process.spawn`, and the `program` and `check` jobs. A program matches by its file name, so `"mermaid-ascii"` covers `${mod.dataFolder}/bin/mermaid-ascii` and the copy in cmod's programs folder |
-| `"files": ["~/.zshrc"]` | Change ~/.zshrc | `mod.fs.write` and `mod.metadata.update` outside the project and the mod's data folder. A folder covers every file below it |
-| `"conversation": true` | Read this conversation | `mod.session.messages`, and reading Claude Code's transcript files |
-| `"prompt": true` | Add text Claude reads and start turns | `mod.session.append`, `mod.session.submit`, the `prompt` and `schedule` jobs, and the hook answers listed below |
-| `"model": true` | Ask a model, which uses your plan | `mod.model.complete` |
-| `"agents": true` | Start agents | `mod.agent.spawn` |
-| `"tools": true` | Use and change Claude's tool calls | `mod.claude.tool.call`, and a hook that changes a tool call's input |
-| `"config": true` | Change your Claude Code settings | writes to `.claude/settings.json`, `.claude/settings.local.json`, and `.mcp.json` |
+| `"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 |
+| `"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 |
+| `"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 |
 
-Reading files, drawing panes and slot renders, toasts, slash commands, tools of the mod's own, and hooks need no permission.
+Reading files, drawing panes and renders, toasts, slash commands, tools of the mod's own, and listeners need no permission. Writing a Claude Code settings file with `fs.write` is refused with every permission, and names the `settings` call to use instead ([mod.md](mod.md#settings-claude-code-s-settings-files)).
 
 `cmod check` adds `"approve": true` to `package.json` when `hooks/register.ts` calls `registerPermissionCheck` and the line is missing, and says so.
 
@@ -46,16 +46,27 @@ The install opens the installer pane in Claude Code and lists every permission i
 ## Check a permission before a feature uses it
 
 ```ts
-mod.permissions.has(name: 'network' | 'run' | 'files', value: string): boolean
-mod.permissions.has(name: 'conversation' | 'prompt' | 'model' | 'agents' | 'tools' | 'config' | 'approve'): boolean
+type Permissions = {
+  readonly conversation: boolean
+  readonly prompt: boolean
+  readonly model: boolean
+  readonly tasks: boolean
+  readonly tools: boolean
+  readonly approve: boolean
+  readonly network: { allows(host: string): boolean }
+  readonly run: { allows(program: string): boolean }
+  readonly files: { allows(path: string): boolean }
+  readonly config: { allows(key: string): boolean }
+}
 ```
 
-`has` says whether the person has the permission turned on, so a mod hides a feature instead of failing it:
+`mod.permissions` says whether the person has each permission turned on, so a mod hides a feature instead of failing it. A flag is `true` while it is granted, and `allows` answers for one host, program, path, or settings key:
 
 ```ts
-if (mod.permissions.has('model')) {
-  const verdict = await mod.model.complete({ prompt: 'Is this reply a waste of time?' })
+if (mod.permissions.model) {
+  const verdict = await model.complete({ model: 'haiku', prompt: 'Is this reply a waste of time?' })
 }
+if (mod.permissions.run.allows('gh')) mod.every(60_000, refreshRuns)
 ```
 
 ## When a call has no grant

package/docs/session.md

@@ -0,0 +1,248 @@
+# Sessions
+
+`sessions` reads and follows Claude Code's conversations: the one the mod runs in, every other one Claude Code saved, and a search across them. A mod never parses a transcript.
+
+```ts
+import { Prompt, sessions } from '../node_modules/@cmodjs/core/mod.js'
+
+const prompts = (await sessions.current.messages()).filter((message) => message.type === Prompt)
+```
+
+Reading a conversation needs the `conversation` permission, sending to one needs `prompt`, and starting a task needs `tasks` ([permissions.md](permissions.md)).
+
+## The shape of a conversation
+
+A session is one conversation. It runs as a series of contexts: a compaction or `/compact` ends one context and starts the next with a summary of the last. Each context holds turns: a turn starts at a prompt and ends when Claude stops. Each turn holds the messages Claude and the people and programs around it exchanged. The session's goal is what the conversation is for, and its tasks are the subagents Claude or a mod started to work beside it.
+
+```
+Session
+├── Goal               what the session is for
+│   └── Task           a subagent working beside Claude
+│       ├── Message    its own messages
+│       └── Task       a task it started
+└── Context            from the start, or a compaction, to the next compaction
+    └── Turn           from a prompt to the end of Claude's answer
+        └── Message    a prompt, a reply, a tool call, and the rest
+```
+
+## sessions
+
+```ts
+type Sessions = {
+  readonly current: Session
+  list(options?: { running?: boolean; since?: string; everyProject?: boolean }): Promise<Session[]>
+  search(text: string, options?: { running?: boolean; since?: string; everyProject?: boolean; limit?: number; before?: Message }): Promise<Message[]>
+}
+```
+
+- `current` is the session the mod runs in. It is there from `setup` on, and follows `/clear`, `/resume`, a fork, `/cd`, and a `cd` in a Bash or PowerShell call.
+- `list` lists the project's sessions, the most recent first. `everyProject` lists every project's, `running` keeps the sessions still open in a Claude Code window, and `since` keeps those active since a time, written as `30m`, `6h`, `2d`, `1w`, or a date such as `2026-10-01`.
+- `search` answers the newest 50 messages whose text contains `text`, any case, in the project's sessions or, with `everyProject`, every project's. `text` is at least 3 characters. `limit` changes the 50, and `before` takes the last message of a page to answer the page after it. A tool call is searched by its name and the first 1,024 characters of each input value, a document by its path and text, and a tool result is not searched.
+
+```ts
+const earlier = await sessions.search('deploy job', { since: '1w' })
+const last = earlier.at(-1)
+const older = last === undefined ? [] : await sessions.search('deploy job', { since: '1w', before: last })
+```
+
+While a mod holds the `conversation` permission, the cmod plugin indexes every conversation in the background at each session's start, so `search` waits only for what changed since. The `cmod history` command answers the same questions in a terminal ([commands.md](commands.md#cmod-history)).
+
+## Session
+
+```ts
+type Session = {
+  readonly id: string
+  readonly title: string
+  readonly project: string
+  readonly cwd: string
+  readonly model: string
+  readonly startedAt: string
+  readonly lastAt: string
+  readonly forkedFrom?: string
+  readonly isRunning: boolean
+  usage(): Promise<Usage>
+  on(event, listener): Disposable
+  on(event, matcher, listener): Disposable
+  send(message: { type: Prompt | Note; text: string; as?: Person | Session }): Promise<void>
+  startTask(task: { prompt: string; agentType?: string; model?: string; name?: string; cwd?: string }): Promise<Task>
+  messages(options?: { after?: string; last?: number }): Promise<Message[]>
+  turns(options?: { last?: number }): Promise<Turn[]>
+  contexts(): Promise<Context[]>
+  goal(): Promise<Goal>
+}
+```
+
+- `id` is Claude Code's session id. `title` is the name the person gave it with `/rename`, or the first line of its first prompt. A resumed or forked session with no name, and a session the mod started in after its first prompt, has an empty `sessions.current.title` until `sessions.list()` reads it.
+- `project` is the project the session works in, and `cwd` is its working folder. For the current session both follow `/cd`, and `cwd` follows a `cd` in a Bash or PowerShell call.
+- `model` is the model the session runs on. `startedAt` and `lastAt` are ISO times.
+- `forkedFrom` names the session a `/branch` or a fork copied it from.
+- `isRunning` is true while the session is open in a Claude Code window.
+- `usage` answers the current session's model, its context window's fill, and its cost so far, as the status line shows them: `{ model, context: { tokens?, window, percent? }, cost?: { usd } }`.
+
+### Read a conversation
+
+- `messages` answers the session's messages in order, those of its tasks left out. `last` keeps that many from the end, and `after` starts after a message's `id`.
+- `turns` answers its turns in order, `last` keeping that many from the end. A turn's `messages()` answers its own.
+- `contexts` answers its contexts in order. A context's `turns()` answers its own.
+- `goal` answers its goal. The goal's `tasks()` answers the tasks Claude or a mod started, and each task's `messages()` and `tasks()` answer its own.
+
+```ts
+const [last] = await sessions.current.turns({ last: 1 })
+const calls = (await last?.messages() ?? []).filter((message) => message.type === ToolCall)
+```
+
+### Listen to a conversation
+
+```ts
+session.on(event: SessionEvent, listener: (payload) => unknown): Disposable
+session.on(event: SessionEvent, matcher: Matcher<payload>, listener: (payload) => unknown): Disposable
+```
+
+`on` runs `listener` for each new message, turn, context, task, or goal change of that session, as it happens. The current session's arrive as Claude Code writes them, and another running session's within a moment.
+
+| Event | The listener gets |
+| --- | --- |
+| `Message` | Every new message. |
+| `Prompt`, `Note`, `Reply`, `ToolCall`, `ToolResult`, `Skill`, `Document`, `Notice` | Each new message of that type. |
+| `TurnStart`, `TurnEnd` | The `Turn` that started or ended. |
+| `ContextStart`, `ContextEnd` | The `Context` that started or ended. |
+| `TaskStart`, `TaskEnd` | The `Task` that started or ended. |
+| `GoalChange` | The `Goal` with its new text. |
+
+A matcher keeps the payloads it matches. It is a partial copy of the payload: a key it names must match, and a key it leaves out matches anything. A string matches the same string, a `RegExp` matches the text it tests true on, and a list matches any one of its items.
+
+```ts
+import { Reply, sessions, ToolCall } from '../node_modules/@cmodjs/core/mod.js'
+
+sessions.current.on(ToolCall, { name: /^(Edit|Write)$/ }, (call) => void (mod.state.session.edits += 1))
+sessions.current.on(Reply, (reply) => mod.log(`Claude said ${reply.text.length} characters`))
+```
+
+A listener that throws shows the error toast `The <event> listener failed`. `dispose()` on the `Disposable` stops the listener.
+
+### Send to a conversation
+
+`send` adds a message to the session, and needs the `prompt` permission.
+
+- A `Note` to the current session is text Claude reads on its next call to the model and the person does not see. It starts no turn. It rejects with `<mod>: Claude Code refused the note: <reason>` when a plugin refuses it.
+- A `Prompt` to the current session is the next prompt, so Claude answers it as a turn of its own. Claude Code holds it until the session is idle, so it never cuts into a turn, and frames it as `The <mod> plugin sent a message:`. With `as: Person`, Claude reads it bare, as the person's own words, while every hook still sees that the mod sent it. It rejects with `<mod>: Claude Code dropped the prompt: <reason>` when a plugin drops it.
+- To another running session, cmod delivers the message, and that session's cmod adds it the same way. `as: Session` sends it as a message from this session instead, which Claude Code shows as one session writing to another.
+- A session that has ended takes no messages, and `send` rejects with `<mod>: session <id> has ended, so it takes no messages.`
+
+A prompt that comes on a clock, such as every 10 minutes, belongs in a `schedule` job instead, which Claude Code shows as one `Running scheduled task` row ([jobs.md](jobs.md#schedule)).
+
+```ts
+mod.every(60_000, async () => {
+  const { stdout } = await process.run(['gh', 'run', 'list', '--limit', '1', '--json', 'conclusion'])
+  if (JSON.parse(stdout)[0]?.conclusion !== 'failure') return
+  await sessions.current.send({ type: Note, text: 'CI failed on the last push.' })
+  await sessions.current.send({ type: Prompt, text: 'Find the cause of the CI failure and fix it.' })
+})
+```
+
+### Start a task
+
+`startTask` starts a subagent in the current session, the way Claude's Agent tool starts one, and resolves the `Task` once it started. It does not wait for the task to finish. `agentType` names an agent type, such as `explorer`, `name` titles the task, and `model` and `cwd` change what it runs on and where. It rejects with `<mod>: Claude Code refused the task: <reason>` when a hook refuses it, and on any session other than the current one.
+
+The task's answer arrives once it finishes, on a `TaskEnd` listener or the mod's `SubagentStop` hook, whose `agent_id` is the task's `id`:
+
+```ts
+const answers = new Map<string, (answer: string) => void>()
+
+mod.on(SubagentStop, (input) => answers.get(input.agent_id)?.(input.last_assistant_message ?? ''))
+
+mod.on(UserPromptSubmit, { prompt: /^\/summarize/ }, async () => {
+  const task = await sessions.current.startTask({ prompt: 'Summarize README.md in one line.', agentType: 'Explore', name: 'Summarize the README' })
+  const summary = await new Promise<string>((resolve) => answers.set(task.id, resolve))
+  return { hookSpecificOutput: { hookEventName: UserPromptSubmit, additionalContext: summary } }
+})
+```
+
+## Message
+
+Every message has these fields, and the fields of its type:
+
+```ts
+type MessageOf<Type> = {
+  readonly id: string
+  readonly type: Type
+  readonly at: string
+  readonly session: string
+  readonly context: number
+  readonly turn?: string
+  readonly task?: string
+}
+```
+
+- `id` names the transcript row the message is in. When one row holds several messages, such as a reply with its tool calls, each `id` ends in `:<n>`. `mod.ui.scroll({ to: { requestId: message.id.split(':')[0] } })` scrolls to the message's row ([ui.md](ui.md#scrolling)).
+- `at` is its ISO time. `session` is the session's id, and `context` the number of the context it is in, from 1.
+- `turn` is the `id` of the prompt that opened its turn. A message before the first prompt, and a task's message, has none.
+- `task` is the id of the task whose message it is. A message of the session itself has none.
+
+| Type | Constant | Its own fields |
+| --- | --- | --- |
+| `'prompt'` | `Prompt` | `text`, `from`: the prompt that opens a turn. A slash command reads as the command typed, such as `/review 12`. |
+| `'note'` | `Note` | `text`, `from`: text Claude reads that is not a prompt, such as a mod's note or a task's notification. |
+| `'reply'` | `Reply` | `text`: what Claude said. |
+| `'toolCall'` | `ToolCall` | `callId`, `name`, `input`, `cwd`: a tool Claude called, and the folder it called it in. |
+| `'toolResult'` | `ToolResult` | `callId`, `text`, `isError`: what the tool answered. |
+| `'skill'` | `Skill` | `name`, `text`: a Skill Claude Code loaded. |
+| `'document'` | `Document` | `path`, `text`: a `CLAUDE.md` file Claude Code read for a folder. |
+| `'notice'` | `Notice` | `text`: a line Claude Code added, such as a model switch. |
+
+`Message` is any of these, and `message.type` tells them apart:
+
+```ts
+for (const message of await sessions.current.messages()) {
+  if (message.type === ToolCall) console.log(message.name, message.input)
+}
+```
+
+### Sender
+
+A prompt's and a note's `from` says who sent it:
+
+```ts
+type Sender = { readonly type: SenderType; readonly name?: string; readonly as?: 'person' }
+```
+
+| `type` | Who sent it |
+| --- | --- |
+| `Person` (`'person'`) | The person, at the keyboard or from a phone. |
+| `'mod'` | A mod, named by `name`. `as: Person` when it sent the prompt as the person's. |
+| `'session'` | Another session. |
+| `'task'` | A task, reporting back. |
+| `Schedule` (`'schedule'`) | A scheduled prompt. |
+| `Channel` (`'channel'`) | A channel, such as Slack, named by `name`. |
+| `Sdk` (`'sdk'`) | A program driving Claude Code through the SDK. |
+
+## Turn, Context, Goal, and Task
+
+```ts
+type Turn = { readonly prompt: Prompt; readonly context: number; readonly openedAt: string; readonly closedAt?: string; messages(): Promise<Message[]> }
+
+type Context = { readonly number: number; readonly openedAt: string; readonly closedAt?: string; turns(): Promise<Turn[]> }
+
+type Goal = { readonly text: string; update(change: { text: string }): Promise<void>; tasks(): Promise<Task[]> }
+
+type Task = {
+  readonly id: string
+  readonly title: string
+  readonly agentType: string
+  readonly model?: string
+  readonly openedBy: string
+  readonly openedAt: string
+  readonly closedAt?: string
+  messages(): Promise<Message[]>
+  tasks(): Promise<Task[]>
+}
+```
+
+- A turn's `closedAt` is set once Claude stops. A turn still running has none.
+- A context's `number` counts from 1. Its `closedAt` is set at the compaction that ended it.
+- A goal's `text` starts as the session's first prompt. `update` replaces it, and a `GoalChange` listener on the current session hears the new text.
+- A task's `openedBy` is the `callId` of the Agent call that started it, and empty for a task a mod started. Its `closedAt` is set once it answered.
+
+## Test it
+
+`testMod` fakes the conversation: `tested.add`, `tested.endTurn`, `tested.compact`, and `tested.startTask` build the current session, and the `sessions` option gives the earlier ones ([testing.md](testing.md#build-a-conversation)).

package/docs/state.md

@@ -1,6 +1,6 @@
 # State
 
-`mod.state` holds the mod's values. Claude Mod Manager (cmod) saves them, redraws the mod's panes and slot renders when one changes, and lets a person change the starting values without touching the mod's code.
+`mod.state` holds the mod's values. Claude Mod Manager (cmod) saves them, redraws the mod's panes and renders when one changes, and lets a person change the starting values without touching the mod's code.
 
 ## Declare the state
 
@@ -9,11 +9,15 @@
 | Group | How long a value lasts | Saved |
 | --- | --- | --- |
 | `memory` | Until `/clear`, `--resume`, `/branch`, or a reload of Claude Code or its plugins. A compaction keeps it. | No |
-| `session` | This conversation. It comes back on `--resume`, starts over on `/clear`, and `/branch` copies it. | Yes |
+| `session` | This conversation. It comes back on `--resume`, starts over on `/clear`, and a fork of the conversation starts with it. | Yes |
 | `project` | This project, in every conversation. | Yes |
 | `global` | Every project. | Yes |
 
-cmod keeps each `session` value for the 20 sessions that wrote it last, and each `project` value for the 20 projects that wrote it last. A session or project past those 20 starts that value over from its starting value.
+cmod keeps each `session` value as long as Claude Code keeps the session's transcript, so a session comes back with its values for as long as `--resume` can find it.
+
+A fork of the conversation, by `/branch`, `claude --resume <id> --fork-session`, or a move to the agents view, starts with the `session` values of the conversation it came from. Outside `/branch`, Claude Code does not say which conversation a fork came from, so the cmod plugin matches the fork's copied conversation to the one it came from, which needs its "Read your Claude Code conversations" permission. A fork starts with the starting values when that permission is off, when it was taken while the conversation it came from was still answering, or in a `-p` run.
+
+cmod keeps each `project` value for the 20 projects that wrote it last, and a project past those 20 starts that value over from its starting value.
 
 Put values the mod works out again on every prompt, such as a git status, in `memory`.
 
@@ -38,14 +42,14 @@ export const initialState: TasksState = {
 Then pass it to `defineMod`:
 
 ```ts
-import { defineMod } from '../node_modules/@cmodjs/core/mod.js'
+import { defineMod, UserPromptSubmit } from '../node_modules/@cmodjs/core/mod.js'
 import { initialState } from './state.js'
 
 export const tasks = defineMod({
   name: 'tasks',
   state: initialState,
   setup(mod) {
-    mod.on('UserPromptSubmit', () => {
+    mod.on(UserPromptSubmit, () => {
       mod.state.session.prompts += 1
     })
   },
@@ -62,13 +66,13 @@ Assign to a key. cmod saves the new value and redraws the mod.
 - An object or an array in the state is frozen. Changing it in place throws `<mod>: mod.state.<path> cannot change in place.` Assign a new value instead:
 
 ```ts
-import { defineMod } from '../node_modules/@cmodjs/core/mod.js'
+import { defineMod, PostToolUse } from '../node_modules/@cmodjs/core/mod.js'
 
 export const reads = defineMod({
   name: 'reads',
   state: { memory: { readFiles: [] as readonly string[] } },
   setup(mod) {
-    mod.on('PostToolUse', (input) => {
+    mod.on(PostToolUse, (input) => {
       mod.state.memory.readFiles = [...mod.state.memory.readFiles, ...input.files.read]
     })
   },

package/docs/testing.md

@@ -34,6 +34,7 @@ type TestOptions<State, Options> = {
   readonly dependencies?: { [Name in keyof CmodDependencies]?: CmodDependencies[Name] }
   readonly files?: Readonly<Record<string, string>>
   readonly links?: Readonly<Record<string, string>>
+  readonly sessions?: readonly FakeSession[]
 }
 ```
 
@@ -43,15 +44,16 @@ type TestOptions<State, Options> = {
 | `options` | The option values Claude Code passes, as a person set them ([options.md](options.md)) | none: each option gets its default |
 | `permissions` | Exactly the permissions the person granted, such as `['network:api.github.com', 'model']` ([permissions.md](permissions.md)) | every permission the mod's `package.json` declares |
 | `scope` | `'project'` makes the mod a project plugin, in `<projectRoot>/.claude/skills/<name>` | `'user'` |
-| `projectRoot` | `mod.projectRoot` | `/test/plugins/<name>`, or `/test/project` for a project plugin |
-| `cwd` | `mod.cwd` | `projectRoot` |
+| `projectRoot` | `sessions.current.project` | `/test/plugins/<name>`, or `/test/project` for a project plugin |
+| `cwd` | `sessions.current.cwd` | `projectRoot` |
 | `dependencies` | The methods other mods answer with | none: every call fails with `<name> is not installed. Run cmod install <name>.` |
 | `files` | The fake file system, absolute path to text | no files |
 | `links` | Symbolic links in the fake file system, absolute link path to its target | no links |
+| `sessions` | The earlier conversations `sessions.list` and `sessions.search` read, each `{ id, messages?, goal?, … }` ([Build a conversation](#build-a-conversation)) | none: only the current session, `test-session` |
 
 A project plugin finds its repository through a `.git` entry at `projectRoot`, so a test of one puts it in `files`, such as `files: { '/test/project/.git': '' }`. Without it the project plugin has no repository, and its rules match calls in every folder, as a user mod's do.
 
-The fake session's id is `test-session`, its model is `test-model`, and its home is `/test/home`. So `mod.dataFolder` is `/test/home/.local/share/cmod/data/<name>`. The mod is installed and draws on a terminal 80 columns wide.
+The fake session's id is `test-session`, its model is `test-model`, and its home is `/test/home`. So `mod.dataFolder` is `/test/home/.local/share/cmod/data/<name>`, and `mod.folder` is `/test/plugins/<name>`. The mod is installed and draws on a terminal 80 columns wide.
 
 ## TestedMod
 
@@ -60,12 +62,16 @@ type TestedMod<State> = {
   start(): Promise<void>
   fire(event, input, below?): Promise<EventResult>
   settle(): Promise<void>
+  add(message: MessageDraft, options?: { task?: string }): Promise<Message[]>
+  endTurn(): Promise<void>
+  compact(): Promise<void>
+  startTask(task: { title: string; agentType?: string; model?: string; openedBy?: string }): Promise<string>
   lines(paneId: string): Promise<string[]>
-  lines(slot, props, requestId?): Promise<string[]>
-  type(line: string): Promise<Reply>
+  lines(place, props, requestId?): Promise<string[]>
+  type(line: string): Promise<CommandReply>
   callTool(name: string, input: Record<string, unknown>): Promise<EventResult<'tool.call'>>
   press(paneId: string, key: string, link?: string): Promise<void>
-  input(paneId: string, key: string, text: string, kind?: 'submit' | 'change'): Promise<void>
+  input(paneId: string, key: string, text: string, type?: 'submit' | 'change'): Promise<void>
   select(paneId: string, key: string, value: string): Promise<void>
   moveTo(projectRoot: string, cwd?: string): Promise<void>
   readonly state: Readonly<State>
@@ -82,13 +88,14 @@ Starts the mod: loads its state, runs `setup`, and adds its hooks, panes, and jo
 ### fire
 
 ```ts
-fire<E extends ModEvent>(event: E, input: TestInput<E>, below?): Promise<EventResult<`classic.${E}`>>
+fire<H extends Hook>(hook: H, input: TestInput<H>, below?): Promise<EventResult<`classic.${H}`>>
 fire<N extends RoutedEvent>(event: N, input: Args<N>, below?): Promise<EventResult<N>>
 ```
 
-- `fire('UserPromptSubmit', { prompt: 'hello' })` runs the mod's hooks on a `ModEvent`. `TestInput<E>` is the event's input without the fields `fire` fills: `session_id`, `transcript_path`, `cwd`, `hook_event_name`, and a new `tool_use_id` for each tool event.
+- `fire(UserPromptSubmit, { prompt: 'hello' })` runs the mod's listeners on a hook. `TestInput<H>` is the hook's input without the fields `fire` fills: `session_id`, `transcript_path`, `cwd`, `hook_event_name`, and a new `tool_use_id` for each tool event.
+- A `SessionStart` that names no `transcript_path` also writes its transcript as an empty file in the test's files, so the session's `session` values last as they do in Claude Code ([state.md](state.md)).
 - For a tool event, `files` is worked out from the call and the test's `files`, as in Claude Code.
-- `fire('PreToolUse', …)` runs the call's `tool.call`, and its `tool.check` inside it, as Claude Code does. `testMod` runs a mod as if `register.ts` calls `registerPermissionCheck`, so it returns `allow: true` or `ask` with the reason when the mod's hooks or `permissions` job decided the permission. A `PreToolUse` with `agent_id` and `agent_type`, such as `fire('PreToolUse', { tool_name: 'Read', tool_input: { file_path: 'a.ts' }, agent_id: 'agent-7', agent_type: 'explorer' })`, runs as that subagent's call. It returns `updatedInput` when the hooks rewrote the input, `additionalContext` as a list, and `deny` when a hook or Claude Code refused the call. Its `below` is `{ deny }` to test a call Claude Code refuses, and Claude Code runs the call otherwise.
+- `fire(PreToolUse, …)` runs the call's `tool.call`, and its `tool.check` inside it, as Claude Code does. `testMod` runs a mod as if `register.ts` calls `registerPermissionCheck`, so it returns `allow: true` or `ask` with the reason when the mod's hooks or `permissions` job decided the permission. A `PreToolUse` with `agent_id` and `agent_type`, such as `fire(PreToolUse, { tool_name: 'Read', tool_input: { file_path: 'a.ts' }, agent_id: 'agent-7', agent_type: 'explorer' })`, runs as that subagent's call. It returns `updatedInput` when the hooks rewrote the input, `additionalContext` as a list, and `deny` when a hook or Claude Code refused the call. Its `below` is `{ deny }` to test a call Claude Code refuses, and Claude Code runs the call otherwise.
 - On every other event, `below` is what the hooks beneath the mod answered. Pass it to test how the mod's answer combines with another. When nothing in the mod answers, `fire` returns `below` as it is.
 - Left out, `below` is `{}`, except on `prompt.submit`, where it is what Claude Code answers: the prompt that entered, `{ text, context, origin }`, with the `context` the mod's hooks added.
 - It returns the combined answer in Claude Code's own field names: `additionalContext` is a list, and `decision: 'block'` is `block`.
@@ -115,7 +122,7 @@ test('a force push is denied with the reason', async () => {
 
 ### Test a prompt with when
 
-A `prompt` with `when` runs on the hook-module event `prompt.submit`, not on `UserPromptSubmit`, so `fire('UserPromptSubmit', …)` never reaches it. `fire('prompt.submit', …)` returns the prompt that entered, with the text the prompt added in its `context`:
+A `prompt` with `when` runs on the hook-module event `prompt.submit`, not on `UserPromptSubmit`, so `fire(UserPromptSubmit, …)` never reaches it. `fire('prompt.submit', …)` returns the prompt that entered, with the text the prompt added in its `context`:
 
 - The `prompt.submit` input is `{ text, wait, origin }`. A prompt the person typed has `wait: false` and `origin: { kind: 'composer' }`.
 - `context` is a list of strings, each `# <name>\n<text>`. The answer has no `context` when no prompt added anything.
@@ -153,26 +160,57 @@ test('a prompt about a release gets the release steps, and another prompt gets n
 
 Waits until the work a hook started without awaiting it has run, such as a `void` call in a `Stop` hook. It returns while a fake the test holds open has not answered.
 
+### Build a conversation
+
+The current session, `test-session`, starts empty. A test builds the conversation the mod reads through `sessions` ([session.md](session.md)), the way Claude Code would write it:
+
+- `add(message, { task? })` adds a message and returns it, placed in its context and turn. A `Prompt` opens a new turn. With `task`, the message is that task's.
+- `endTurn()` ends the open turn, as Claude stopping does.
+- `compact()` ends the context and starts the next, as a compaction does.
+- `startTask({ title, agentType?, model?, openedBy? })` starts a task and returns its id.
+
+Each one runs the mod's session listeners, as a new message does in Claude Code. A `MessageDraft` is a message without its place: `{ type: Prompt, text, from? }`, `{ type: Note, text, from? }`, `{ type: Reply, text }`, `{ type: ToolCall, name, input?, callId? }`, `{ type: ToolResult, callId, text, isError? }`, `{ type: Skill, name, text }`, `{ type: Document, path, text }`, or `{ type: Notice, text }`.
+
+The `sessions` option gives the earlier conversations, each a `FakeSession`: an `id`, its `messages` as drafts, its `goal`, and any `Session` field, such as `title`, `project`, or `isRunning`. A session that names no `project` is in the test's project.
+
+```ts
+import { expect, test } from 'bun:test'
+import { Prompt, Reply } from '../node_modules/@cmodjs/core/mod.js'
+import { testMod } from '../node_modules/@cmodjs/core/testing.js'
+import { recall } from '../src/mod.js'
+
+test('/recall finds the earlier session about the deploy', async () => {
+  const tested = testMod(recall, { sessions: [{ id: 'older', title: 'Fix the deploy', messages: [{ type: Prompt, text: 'Why did the deploy fail?' }] }] })
+  await tested.add({ type: Prompt, text: 'Recall the deploy' })
+  await tested.add({ type: Reply, text: 'Looking.' })
+  await tested.endTurn()
+
+  expect(await tested.type('/recall deploy')).toEqual({ text: 'Fix the deploy: Why did the deploy fail?' })
+})
+```
+
+`shown.sent` lists what the mod sent to other sessions. `fakes.agent.spawn` answers `startTask`, such as `async () => ({ agentId: 'agent-7', model: 'test-model' })`.
+
 ### lines
 
 - `lines(paneId)` draws an open pane and returns its rows of text. It rejects a pane that is not open: open it first with `tested.type('/<command>')` or `pane.open()` in the mod. The render gets the props `title`, `isFocused`, true once an `open` or `toggle` with `{ focus: true }` opened it, `bodyColumns`, `placement: 'dock'`, `scroll: { offset: 0, bodyRows: 24 }`, and `view: {}`, the main conversation's view.
 - A `Button` draws as Claude Code draws it: `[ Save ]`, or `1: Save` when it is `plain` with a `hotkey`, or `Save` when it is `plain` alone. Borders and colors are not drawn.
-- `lines(slot, props, requestId?)` draws a slot render with `props` and returns its rows. `Default` draws a plain listing of the props it gets, so a test sees what the render changed. Draw `slots.AssistantMessage` with a reply's `text` to test a markdown slot render. Draws that pass one `requestId` grow one streamed reply.
+- `lines(place, props, requestId?)` draws a place render with `props` and returns its rows. `Default` draws a plain listing of the props it gets, so a test sees what the render changed. Draw `Reply` with a reply's `text` to test a markdown place render. Draws that pass one `requestId` grow one streamed reply. `AbovePrompt` ends with the toasts shown now, under the mod's own rows.
 
 ```ts
 import { expect, test } from 'bun:test'
 import type { RenderPropsOf } from 'claude-code'
+import { AbovePrompt, UserPromptSubmit } from '../node_modules/@cmodjs/core/mod.js'
 import { testMod } from '../node_modules/@cmodjs/core/testing.js'
-import { slots } from '../node_modules/@cmodjs/core/ui/slots.js'
 import { hints } from '../src/mod.js'
 
 const band: RenderPropsOf['AbovePrompt'] = { hasSurvey: false, isWorking: false, maxRows: 12, bodyColumns: 75, scroll: { offset: 0, bodyRows: 12 }, view: {} }
 
-test('the band shows the prompt count on its last line', async () => {
+test('the band shows the prompt count', async () => {
   const tested = testMod(hints)
-  await tested.fire('UserPromptSubmit', { prompt: 'hello' })
+  await tested.fire(UserPromptSubmit, { prompt: 'hello' })
 
-  expect((await tested.lines(slots.AbovePrompt, band)).at(-1)).toBe('Prompts: 1')
+  expect(await tested.lines(AbovePrompt, band)).toContain('Prompts: 1')
 })
 ```
 
@@ -190,7 +228,7 @@ test('the band shows the prompt count on its last line', async () => {
 
 - `press(paneId, key)` presses the `Button` whose `key` or `label` is `key`, and runs its `onPress`.
 - `press(paneId, key, link)` presses the link `link` in the `Markdown` whose `key` is `key`, and runs its `onLinkPress`.
-- `input(paneId, key, text)` types `text` into the `Input` whose `key` is `key` and presses Enter, which runs its `onSubmit`. With `kind` `'change'` it runs `onInput` instead, as one edit does.
+- `input(paneId, key, text)` types `text` into the `Input` whose `key` is `key` and presses Enter, which runs its `onSubmit`. With `type` `'change'` it runs `onInput` instead, as one edit does.
 - `select(paneId, key, value)` picks the option `value` of the `Select` whose `key` is `key`, and runs its `onSelect`. It rejects an option the `Select` does not have.
 
 ```ts
@@ -201,7 +239,7 @@ expect(await tested.lines('history')).toContain('deploy by explorer')
 
 ### moveTo
 
-`moveTo(projectRoot, cwd?)` moves the session. A new `projectRoot` runs a `/cd` there, so the mod loads that project's state. A `cwd` then runs a Bash `cd` there. The mod's `CwdChanged` hooks run for each move.
+`moveTo(projectRoot, cwd?)` moves the session. A new `projectRoot` runs a `/cd` there, so the mod loads that project's state. A `cwd` then runs a Bash `cd` there. The mod's `CwdChanged` listeners run for each move, and `sessions.current` follows it.
 
 ### state
 
@@ -235,20 +273,22 @@ Set a fake to answer a call:
 
 - A call with no fake throws `<call>(<args>) has no fake answer. Set fakes.<call> on the tested mod.` So set `fakes.process.run` before a test runs a program, and `fakes.ui.ask` before the mod asks a question.
 - A `program` job is the exception: it catches the `process.spawn` error and retries after 1, 2, 4, 8 and 16 seconds on real timers, so its `ready()` waits past `bun test`'s 5-second timeout. Set `fakes.process.spawn` before a test starts a `program` job.
-- `files` already fills the `fs` fakes: a write is read back, and `list` lists the given files. The fake file system resolves a relative path against `/`, not against `mod.cwd`, so a mod under test reads `${mod.projectRoot}/<file>` rather than a relative path. `fs.list()` with no path rejects.
+- `files` already fills the `fs` fakes: a write is read back, and `list` lists the given files. The fake file system resolves a relative path against `/`, not against the session's working folder, so a mod under test reads `${sessions.current.project}/<file>` rather than a relative path. `fs.list()` with no path rejects.
 - `ui.open` places every pane by default. A fake that answers `{ isPlaced: false }` holds a pane back.
 - `ui.scroll` answers `{}` by default, as when the window moved. A fake that answers `{ deny }` refuses the scroll.
 - `clock.after(ms, fn)` and `clock.every(ms, fn)` each return `{ cancel() }`, and so must a fake of either. `clock.after` runs a real timer by default. `clock.every` never fires unless a fake keeps `fn` for the test to call, so a test of `mod.every` keeps it and calls it once per tick.
 - `session.append` and `prompt.submit` take every note and prompt by default, into `shown.notes` and `shown.prompts`. A fake that answers `{ deny }` or `{ drop }` refuses one.
 - `model.complete` has no default: set it to the answer the model gives, such as `async () => ({ isAnswered: true, text: 'no', usage })`.
+- `settings.read` answers `{}` by default, as Claude Code does with no `settings.json` files.
 - `config.list` answers no `/config` rows by default. A `config.list` fake that answers a row with `isLocked: true` locks that option as managed settings do.
 - `tool.call` answers `CronCreate`, `CronDelete`, and `CronList` by default, keeping the crons a `schedule` makes in `shown.schedules`. A call to any other tool needs a fake.
-- `files` takes symbolic links too: `testMod(mod, { files, links: { '/work/skills': '/shared/skills' } })` makes `/work/skills` a link to `/shared/skills`, so a test of `mod.fs.find` or `mod.metadata.update` follows it as a real file system does.
+- `files` takes symbolic links too: `testMod(mod, { files, links: { '/work/skills': '/shared/skills' } })` makes `/work/skills` a link to `/shared/skills`, so a test of `fs.find` or `metadata.update` follows it as a real file system does.
 - `testMod` runs no installer pane: an option with no default and no value fails `start()` with its fix, and the `installer` steps are not shown. Test a step's `render` and `isDone` by calling them with the started `mod`.
 - The `committer` below runs `git`, so its `package.json` declares `"permissions": { "run": ["git"] }`. A gated call the mod does not declare fails before it reaches a fake ([permissions.md](permissions.md)).
 
 ```ts
 import { expect, test } from 'bun:test'
+import { Stop } from '../node_modules/@cmodjs/core/mod.js'
 import { testMod } from '../node_modules/@cmodjs/core/testing.js'
 import { committer } from '../src/mod.js'
 
@@ -257,7 +297,7 @@ test('a Commit answer commits', async () => {
   tested.fakes.ui.ask = async () => 'Commit'
   tested.fakes.process.run = async () => ({ exitCode: 0, stdout: '', stderr: '', isStdoutTruncated: false, isStderrTruncated: false })
 
-  await tested.fire('Stop', { stop_hook_active: false })
+  await tested.fire(Stop, { stop_hook_active: false })
 
   expect(tested.calls.filter(({ call }) => call === 'process.run').map(({ args }) => args[0])).toEqual([['git', 'commit', '-am', 'wip']])
 })
@@ -267,7 +307,7 @@ test('a Commit answer commits', async () => {
 
 ```ts
 type Shown = {
-  readonly toasts: string[]
+  readonly toasts: ShownToast[]
   readonly notes: string[]
   readonly prompts: string[]
   readonly logs: string[]
@@ -277,10 +317,13 @@ type Shown = {
   readonly commands: string[]
   readonly tools: string[]
   readonly schedules: { readonly id: string; readonly cron: string; readonly prompt: string }[]
+  readonly sent: { readonly session: string; readonly type: string; readonly text: string; readonly as?: string }[]
 }
+
+type ShownToast = { readonly type: ToastType; readonly message: string; readonly description?: string }
 ```
 
-What the person and Claude would see: the toasts, the notes the mod added for Claude with `mod.session.append` or a `prompt` that follows the state, the prompts it sent with `mod.session.submit`, the log lines, the debug log lines, each status line text, the open panes, the slash commands and tools the mod added, and the crons its `schedule` keeps now.
+What the person and Claude would see: the toasts shown now, with a text description, the notes the mod added for Claude with `sessions.current.send` or a `prompt` that follows the state, the prompts it sent to the current session, the messages it sent to other sessions in `sent`, the log lines, the debug log lines, each status line text, the open panes, the slash commands and tools the mod added, and the crons its `schedule` keeps now.
 
 ```ts
 test('the Mode prompt follows the mode', async () => {