@cmodjs/core 0.3.0 → 1.5.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`, `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 | 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 |
 
-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,311 @@
+# 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 and changing its text need `prompt`, calling a tool and changing a tool call need `tools`, and starting or changing a task needs `tasks` ([permissions.md](permissions.md)).
+
+## The shape of a conversation
+
+A session is one agent and its record. 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 the agent stops. Each turn holds the messages the agent and the people and programs around it exchanged. The session's goal is what it is for, and its tasks are the work it handed to other sessions. Each task's `owner` is the session that does that work, such as an `Explore` subagent, with a record of its own.
+
+```
+Session                one agent and its record
+├── Goal               what the session is for
+│   └── Task           work handed to another session
+│       ├── owner      the Session doing it, with its own goal, turns, and messages
+│       └── Task       a task its owner handed on
+└── Context            from the start, or a compaction, to the next compaction
+    └── Turn           from a prompt to the end of the agent's answer
+        └── Message    a prompt, a reply, a tool call, and the rest
+```
+
+Every part of the record answers the same three calls: `search` finds its messages, `on` hears what happens in it, and `before` changes or refuses what is about to happen in it.
+
+## 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[]>
+  on(event, listener): Disposable
+  on(event, matcher, listener): Disposable
+  before(event, listener): Disposable
+  before(event, matcher, listener): Disposable
+}
+```
+
+- `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 })
+```
+
+- `on` and `before` hear every running session of the project, this one included ([Listen](#listen-to-a-record), [Change what happens](#change-what-happens)).
+
+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 agentType?: string
+  readonly model: string
+  readonly cwd: string
+  readonly isRunning: boolean
+  readonly startedAt: string
+  readonly lastAt: string
+  readonly forkedFrom?: string
+  goal(): Promise<Goal>
+  context(): Promise<Context>
+  contexts(): Promise<Context[]>
+  turn(): Promise<Turn | undefined>
+  turns(options?: { last?: number }): Promise<Turn[]>
+  messages(options?: { after?: string; last?: number }): Promise<Message[]>
+  search(text: string, options?: { limit?: number; before?: Message }): Promise<Message[]>
+  on(event, listener): Disposable
+  on(event, matcher, listener): Disposable
+  before(event, listener): Disposable
+  before(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>
+  callTool(call: { name: string; input: Record<string, unknown> }): Promise<ToolResult>
+  usage(): Promise<Usage>
+  clients(): Promise<Client[]>
+}
+```
+
+- `id` is Claude Code's session id, and a task owner's `id` is its task's 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.
+- `agentType` is the agent definition the session runs, such as `Explore` for a task's owner, or the agent a session started with `claude --agent` runs. A plain session has none.
+- `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, and for a task's owner while its task runs.
+
+### Read a record
+
+- `goal` answers its goal. The goal's `tasks()` answers the tasks the session handed on, and each task's `owner` reads like any session.
+- `context` answers the context it is in now, and `contexts` all of them in order. A context's `turns()` answers its own.
+- `turn` answers the turn running now, and nothing between turns. `turns` answers its turns in order, `last` keeping that many from the end. A turn's `messages()` answers its own.
+- `messages` answers its messages in order, those of its tasks left out. `last` keeps that many from the end, and `after` starts after a message's `id`.
+- `search` finds its messages whose text contains `text`, newest first, the way `sessions.search` does. A goal's, a task's, a context's, and a turn's `search` find only their own.
+
+```ts
+const [last] = await sessions.current.turns({ last: 1 })
+const calls = (await last?.messages() ?? []).filter((message) => message.type === ToolCall)
+const explorers = (await (await sessions.current.goal()).tasks()).filter((task) => task.owner.agentType === 'Explore')
+```
+
+A session that has ended keeps its record, so every read works on it.
+
+### Listen to a record
+
+```ts
+part.on(event: SessionEvent, listener: (payload) => unknown): Disposable
+part.on(event: SessionEvent, matcher: Matcher<payload>, listener: (payload) => unknown): Disposable
+```
+
+`on` runs `listener` for each new message, turn, context, task, goal change, or usage change, as it happens. `sessions`, a session, its goal, a task, a context, and a turn each have `on`, and each hears what happens inside it: an event reaches the part it happens in and every part above it.
+
+```
+Message ──> Turn ──> Context ──> Session ──> sessions
+TaskStart, TaskEnd, and the owner's record ──> Task ──> its parent Task ──> Goal ──> Session
+```
+
+So `turn.on(Reply, …)` hears the replies of that turn only, `task.on(Message, …)` hears every message of the task's owner and of the tasks it handed on, and `sessions.on(Prompt, …)` hears every prompt of every running session in the project.
+
+| Event | The listener gets | It happens in |
+| --- | --- | --- |
+| `Message` | Every new message. | Its turn |
+| `Prompt`, `Note`, `Reply`, `ToolCall`, `ToolResult`, `Skill`, `Document`, `Notice` | Each new message of that type. | Its turn |
+| `TurnStart`, `TurnEnd` | The `Turn` that started or ended. | Its context |
+| `ContextStart`, `ContextEnd` | The `Context` that started or ended. | The session |
+| `TaskStart`, `TaskEnd` | The `Task` that started or ended. | Its parent task, or the goal |
+| `GoalChange` | The `Goal` with its new text. | The goal |
+| `UsageChange` | The session's new `Usage`. | The session |
+
+The current session's events arrive as Claude Code writes them, and another running session's within a moment.
+
+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. A key the payload lacks matches nothing.
+
+```ts
+import { Reply, sessions, TaskStart, 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(TaskStart, { owner: { agentType: 'Explore' } }, (task) => mod.log(`Exploring: ${task.title}`))
+```
+
+A listener that throws shows the error toast `The <event> listener failed`. `dispose()` on the `Disposable` stops the listener.
+
+### Change what happens
+
+```ts
+part.before(event: BeforeEvent, listener: (payload) => Answer | void): Disposable
+part.before(event: BeforeEvent, matcher: Matcher<payload>, listener: (payload) => Answer | void): Disposable
+```
+
+`before` runs `listener` just before something happens, and its answer changes or refuses it. Returning nothing lets it happen as it was. Each part has `before`, and hears what is about to happen inside it, the way `on` does.
+
+| Event | The listener can answer | Covers |
+| --- | --- | --- |
+| `Prompt` | `{ text }` or `{ refuse }` | A typed prompt, a mod's prompt, a slash command, and a message from another session |
+| `Note` | `{ text }` | A note any mod or Claude Code adds |
+| `Skill` | `{ text }` | A Skill as Claude Code loads it |
+| `Document` | `{ text }` or `{ refuse }` | A `CLAUDE.md` file as Claude Code reads it. `refuse` leaves it out |
+| `Reply`, `ToolResult`, `Notice` | `{ text }` | The text the transcript keeps |
+| `ToolCall` | `{ input }`, `{ result }`, or `{ refuse }` | A tool call. `result` answers it without running the tool |
+| `TaskStart` | `{ owner: { model } }` or `{ refuse }` | A task about to start, and the model its owner runs |
+| `TaskEnd` | `{ refuse }` | A task about to end. `refuse` sends its owner on with the reason |
+| `TurnEnd` | `{ refuse }` | The agent about to stop. `refuse` sends it on with the reason |
+| `ContextEnd` | `{ refuse }` | A compaction about to start. `refuse` keeps the context |
+
+```ts
+sessions.current.before(ToolCall, { name: 'Bash', input: { command: /\brm -rf\b/ } }, () => ({ refuse: 'Delete files one at a time.' }))
+sessions.current.before(TaskStart, { owner: { agentType: 'Explore' } }, () => ({ owner: { model: 'haiku' } }))
+sessions.current.before(TurnEnd, async () => ((await testsPass()) ? undefined : { refuse: 'The tests fail. Fix them before you stop.' }))
+```
+
+An answer that changes text needs the `prompt` permission, a `ToolCall` answer needs `tools`, and a `TaskStart` or `TaskEnd` answer needs `tasks`. Without it the answer changes nothing, and the toast `The before(<event>) listener failed` names the permission. When several listeners answer, each sees what the one before it changed, and the first `refuse` or `result` decides.
+
+`before` on another session, and `sessions.before`, ask the mod over cmod from that session. That session waits up to 5 seconds for the answer, then lets the event happen as it was and logs why. `sessions.before` answers once for each event, whichever session it happens in.
+
+### Act on a session
+
+Every action works on the current session and on every other running session. cmod carries an action to another session, and that session's cmod does it there.
+
+- `send` adds a message to the session, and needs the `prompt` permission.
+  - A `Note` is text the agent 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` is the next prompt, so the agent 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`, the agent 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.
+  - `as: Session` sends it to another session as a message from this one, which Claude Code shows as one session writing to another.
+  - To a task's owner, `send` delivers the text to that running subagent.
+- `startTask` starts a task in the session, the way the Agent tool starts one, and resolves the `Task` once it started. It does not wait for the task to finish. `agentType` names the owner's agent type, such as `Explore`, `name` titles the task, and `model` and `cwd` change what it runs on and where. It needs the `tasks` permission, and rejects with `<mod>: Claude Code refused the task: <reason>` when a hook refuses it.
+- `callTool` runs a tool in the session, such as `{ name: 'Bash', input: { command: 'bun test' } }`, and resolves its `ToolResult`. It needs the `tools` permission.
+- `usage` answers the 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 } }`. For an ended session and a task's owner it answers the model and the tokens of its last reply, from its transcript.
+- `clients` answers the Claude apps showing the session now: `'terminal'`, `'desktop'`, `'mobile'`, and `'vscode'`. An ended session shows in none.
+
+A task's owner takes `send`, `usage`, and `clients`. Claude Code gives a subagent no way to start a task or run a tool from outside, so its `startTask` and `callTool` reject. An action on a session that has ended rejects with `session <id> has ended`, and `send` 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.' })
+})
+```
+
+The task's answer arrives once it finishes, on a `TaskEnd` listener:
+
+```ts
+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 ended = await new Promise<Task>((resolve) => task.on(TaskEnd, resolve))
+  const [answer] = await ended.owner.messages({ last: 1 })
+  return { hookSpecificOutput: { hookEventName: UserPromptSubmit, additionalContext: answer?.type === Reply ? answer.text : '' } }
+})
+```
+
+## 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 task's message names its owner's turn. A message before the first prompt 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[]>; search; on; before }
+
+type Context = { readonly number: number; readonly openedAt: string; readonly closedAt?: string; turns(): Promise<Turn[]>; search; on; before }
+
+type Goal = { readonly text: string; tasks(): Promise<Task[]>; search; on; before; update(change: { text: string }): Promise<void> }
+
+type Task = {
+  readonly id: string
+  readonly title: string
+  readonly owner: Session
+  readonly openedBy: string
+  readonly openedAt: string
+  readonly closedAt?: string
+  tasks(): Promise<Task[]>
+  messages(): Promise<Message[]>
+  search; on; before
+}
+```
+
+- A turn's `closedAt` is set once the agent 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 hears the new text.
+- A task's `owner` is the session doing the work. Its goal is the task's prompt, its `agentType` and `model` are what the task runs, and its turns and messages are the task's own. Claude Code's checklist tools, `TaskCreate`, `TaskUpdate`, and `TaskList`, are not tasks: they are its todo list, which the `TodoCreated` and `TodoCompleted` hooks hear ([hooks.md](hooks.md)).
+- 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]
     })
   },