@cmodjs/core 0.1.8 → 0.1.10

package/docs/commands.md

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

package/docs/hooks.md

@@ -7,12 +7,29 @@
 ```ts
 mod.on<E extends ModEvent>(event: E, hook: ModHook<E>): void
 
-type ModHook<E> = (input: HookInputs[E]) => HookAnswer | void | Promise<HookAnswer | void>
+type ModHook<E> = (input: HookInput<E>) => HookAnswer | void | Promise<HookAnswer | void>
 ```
 
 Add hooks in `setup`. Each `mod.on` adds one more hook. Several hooks on one event all run.
 
-A hook on `PreToolUse` or `PermissionRequest` takes part in Claude Code's permission check, so the mod's `hooks/register.ts` calls `registerPermissionCheck(addHook)` after `registerMod` ([mod.md](mod.md)). Without it the mod does not start.
+`HookInput<E>`, exported from `mod.js`, is the input a hook on `E` gets, for a hook that lives in a function of its own:
+
+```ts
+import type { HookAnswer, HookInput, Mod } from '../node_modules/@cmodjs/core/mod.js'
+
+export async function addBranch(mod: Mod, input: HookInput<'SessionStart'>): Promise<HookAnswer | undefined> {
+  const { stdout } = await mod.process.run(['git', 'branch', '--show-current'], { cwd: input.cwd })
+  return { hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: `The git branch is ${stdout.trim()}.` } }
+}
+```
+
+A `PreToolUse` hook runs on Claude Code's `tool.call`, before Claude Code checks the call's permission. It rewrites the call's input, adds context to it, or denies it, and Claude Code's permission check sees the rewritten input. A `permissionDecision` of `'allow'` or `'ask'` decides the call's permission, so it takes effect in Claude Code's permission check, and only when the mod's `hooks/register.ts` calls `registerPermissionCheck(addHook)` after `registerMod` ([mod.md](mod.md)):
+
+- `'allow'` runs the call without asking the person, and `'ask'` asks them, with `permissionDecisionReason` as the question's reason.
+- A deny from a settings rule or another hook still denies the call, and the mod's own `permissions` job can still ask or deny.
+- Without `registerPermissionCheck`, an `'allow'` or `'ask'` denies the call with `<mod>: the PreToolUse hook answered permissionDecision "allow", so hooks/register.ts must call registerPermissionCheck(addHook) after registerMod.`
+
+A hook on `PermissionRequest` takes part in that check too, so a mod with one does not start without `registerPermissionCheck`.
 
 ```ts
 import { defineMod } from '../node_modules/@cmodjs/core/mod.js'
@@ -31,7 +48,7 @@ export const safeDelete = defineMod({
 
 ## Every ModEvent
 
-`ModEvent` names the 17 events a mod hooks. The input of each is the hook input a `settings.json` hook reads for that event, typed as `ClassicHookInputs['<event>']` in the `claude-code` module, with the changes this table names.
+`ModEvent` names the 18 events a mod hooks. The input of each is the hook input a `settings.json` hook reads for that event, typed as `ClassicHookInputs['<event>']` in the `claude-code` module, with the changes this table names.
 
 | Event | Input changes |
 | --- | --- |
@@ -52,9 +69,17 @@ export const safeDelete = defineMod({
 | `Stop` | none |
 | `StopFailure` | none |
 | `CwdChanged` | no `transcript_path` |
+| `FileChanged` | none |
 
 cmod raises `CwdChanged` itself, never Claude Code. It raises it when the working folder changes: after `/cd`, after a Bash or PowerShell call, and at a prompt. `mod.cwd` and `mod.projectRoot` already hold the new folder when the hook runs.
 
+Claude Code raises `FileChanged` when a file it watches changes, with the file's `file_path` and `event`: `'change'`, `'add'`, or `'unlink'`. It watches the paths a `SessionStart` hook answers in `watchPaths`:
+
+```ts
+mod.on('SessionStart', () => ({ hookSpecificOutput: { hookEventName: 'SessionStart', watchPaths: [`${mod.dataFolder}/history`] } }))
+mod.on('FileChanged', ({ file_path, event }) => mod.ui.toast(`${file_path}: ${event}`))
+```
+
 ## files: what a tool call reads and changes
 
 The input of `PreToolUse`, `PostToolUse`, and `PostToolUseFailure` has `files: { read: string[]; changed: string[] }`, absolute paths that cmod works out from the call:
@@ -65,6 +90,37 @@ The input of `PreToolUse`, `PostToolUse`, and `PostToolUseFailure` has `files: {
 - `read` lists only paths that are files now. `changed` lists every path the call writes, whether it exists or not.
 - When cmod cannot work the files out, both lists are empty, and the reason goes to Claude Code's debug log.
 
+## shell.js and path.js: read a command line
+
+`shell.js` reads a Bash line the way cmod does for `files`, and `path.js` is `node:path`'s POSIX functions, which a mod cannot import from Node:
+
+```ts
+parseShell(line: string): ParsedShell
+
+type ParsedShell = { commands: ShellCommand[]; reads: string[]; writes: string[]; fetches: string[]; isFullyParsed: boolean }
+type ShellCommand = { argv: [string, ...string[]]; folder: string }
+
+resolve(...paths): string   join(...paths): string   dirname(path): string   basename(path, suffix?): string
+extname(path): string        relative(from, to): string   isAbsolute(path): boolean   normalize(path): string
+```
+
+- `commands` lists every command the line runs, those inside `sudo`, `bash -c`, `$(…)`, and heredocs included, with flags such as `-rf` split into `-r` and `-f`.
+- `folder` is where a command runs, as the line wrote it: `''` for the folder the line starts in, `src` after `cd src`, `/tmp` after `cd /tmp`, and `~/p` after `cd ~/p`. `resolve(input.cwd, folder)` makes it absolute.
+- `reads`, `writes`, and `fetches` are the paths and URLs the commands name, as written. A path that holds a shell expansion makes `isFullyParsed` false, and so does a line the parser cannot read.
+- `resolve` has no working folder to start from in Claude Code's hooks, so pass an absolute folder first, such as `resolve(mod.cwd, path)`.
+
+```ts
+import { basename, resolve } from '../node_modules/@cmodjs/core/path.js'
+import { parseShell } from '../node_modules/@cmodjs/core/shell.js'
+
+mod.on('PreToolUse', (input) => {
+  if (input.tool_name !== 'Bash') return
+  for (const { argv, folder } of parseShell(String(input.tool_input['command'])).commands) {
+    if (basename(argv[0]) === 'trace') mod.ui.toast(`trace runs in ${resolve(input.cwd, folder)}`)
+  }
+})
+```
+
 ## HookAnswer: what a hook can answer
 
 Return nothing to leave the event as it is. Return a `HookAnswer` to change it. The fields are the ones a `settings.json` hook writes as JSON:
@@ -108,12 +164,12 @@ Each event reads only some `hookSpecificOutput` fields:
 | --- | --- |
 | `SessionStart` | `additionalContext`, `initialUserMessage`, `sessionTitle`, `watchPaths`, `reloadSkills` |
 | `UserPromptSubmit` | `additionalContext`, `sessionTitle`, `suppressOriginalPrompt` |
-| `PreToolUse` | `additionalContext`, `permissionDecision`, `permissionDecisionReason`, `updatedInput` |
+| `PreToolUse` | `additionalContext`, `permissionDecision` (`'allow'` and `'ask'` need `registerPermissionCheck`), `permissionDecisionReason`, `updatedInput` |
 | `PermissionRequest` | `decision` |
 | `PermissionDenied` | `retry` |
 | `PostToolUse` | `additionalContext`, `updatedToolOutput`, `updatedMCPToolOutput` |
 | `PostToolUseFailure`, `PostToolBatch`, `SubagentStart`, `SubagentStop`, `Stop` | `additionalContext` |
-| `SessionEnd`, `InstructionsLoaded`, `Notification`, `PreCompact`, `StopFailure`, `CwdChanged` | none |
+| `SessionEnd`, `InstructionsLoaded`, `Notification`, `PreCompact`, `StopFailure`, `CwdChanged`, `FileChanged` | none |
 
 A field the event does not read is an error: `it answered hookSpecificOutput.<field>, which <event> does not read. Remove it from the answer.` A flag set to `false`, such as `retry: false`, counts as unset.
 
@@ -122,7 +178,7 @@ A field the event does not read is an error: `it answered hookSpecificOutput.<fi
 Every mod's hooks and Claude Code's own `settings.json` hooks answer the same event.
 
 - `additionalContext` from every hook reaches Claude, each in turn.
-- On `PreToolUse` the strictest decision wins: `deny` over `ask` over `allow`. A mod's `allow` never overrides a `deny` from another hook.
+- `PreToolUse` hooks run one inside the next, in the order mods and `mod.on` added them. A deny stops the call there, so no hook after it runs. `updatedInput` replaces the tool's input for every hook after it and for Claude Code. `additionalContext` reaches Claude with the call's result, and not at all when Claude Code refuses the call.
 - For every other field, the mod's answer replaces the answer of the hooks beneath it.
 
 ```ts

package/docs/index.md

@@ -32,9 +32,9 @@ The template is a working example to replace. It counts the prompts of the sessi
 
 A mod imports `@cmodjs/core` by path, such as `../node_modules/@cmodjs/core/mod.js`, because Claude Code loads a plugin's own files only. Types such as `RenderElement` and `On` come from the `claude-code` module.
 
-## Type-check after the first session
+## Claude Code's types
 
-Claude Code writes `.claude-plugin/types/` the first time a session loads the mod. That folder holds the `tsconfig.json` the mod's own extends, the `claude-code` module, and the `h` JSX global. Until it exists, `tsc` fails, and `cmod check` skips its type check. Run `cmod link`, start `claude` once, then type-check. A project plugin needs no link: start `claude` in its repository and trust it.
+`.claude-plugin/types/` holds the `tsconfig.json` the mod's own extends, the `claude-code` module, and the `h` JSX global. Claude Code writes it when it loads the mod, and git ignores it. `cmod check` has Claude Code write it when it is missing, so a fresh clone and CI type-check too. Until it exists, `tsc` alone fails, so run `cmod check` once first.
 
 ## Where a mod runs
 
@@ -72,12 +72,15 @@ A mod imports from the files below, and every other file in this package is inte
 | --- | --- | --- |
 | `mod.js` | `defineMod`, `ModDefinition`, `Mod`, `JobContext`, `Job`, `ProgressStep`, `PaneHandle`, `longestMs`, `messageOf` | [mod.md](mod.md), [jobs.md](jobs.md), [ui.md](ui.md) |
 | `mod.js` | `Claude`, `RoutedEvent`, `RoutedHook`, `ToolCalls` | [jobs.md](jobs.md) |
-| `mod.js` | `ModEvent`, `ModHook`, `HookAnswer` | [hooks.md](hooks.md) |
+| `mod.js` | `ModEvent`, `ModHook`, `HookInput`, `HookAnswer` | [hooks.md](hooks.md) |
 | `mod.js` | `notInstalled` | [dependencies.md](dependencies.md) |
 | `register.js` | `registerMod`, `registerPermissionCheck` | [mod.md](mod.md) |
+| `shell.js` | `parseShell`, `ParsedShell`, `ShellCommand` | [hooks.md](hooks.md) |
+| `path.js` | `resolve`, `join`, `dirname`, `basename`, `extname`, `relative`, `isAbsolute`, `normalize` | [hooks.md](hooks.md) |
 | `testing.js` | `testMod`, `TestOptions`, `TestInput`, `TestedMod`, `Fakes`, `Shown`, `TestCall` | [testing.md](testing.md) |
 | `ui/define-pane.js` | `definePane`, `Pane` | [ui.md](ui.md) |
 | `ui/elements.js` | `Box`, `Text`, `Button`, `Link`, `Code`, `Markdown`, `Input`, `Select`, `Image`, `drawWith` | [ui.md](ui.md) |
+| `ui/components.js` | `Tabs`, `Tab`, `Split`, `Panel`, `Toggle`, `Tooltip`, `Help`, `Dialog`, `Pagination`, `ProgressBar` | [ui.md](ui.md) |
 | `ui/slots.js` | `slots`, `Slot`, `SlotProps` | [ui.md](ui.md) |
 | `ui/markdown.js` | `markdownSlots`, `markdownBlocks`, `MarkdownKind`, `MarkdownReader`, `MarkdownPiece` | [ui.md](ui.md) |
 | `jobs/slash-command.js` | `slashCommand`, `Reply` | [jobs.md](jobs.md) |
@@ -98,4 +101,4 @@ A mod imports from the files below, and every other file in this package is inte
 
 ## Check your work
 
-Run `cmod check` in the mod's folder. It installs the packages, checks the layout and the imports, validates the mod with Claude Code, type-checks it once `.claude-plugin/types/` exists, lints it, and runs its tests. Each failure names its fix. [commands.md](commands.md) lists every step.
+Run `cmod check` in the mod's folder. It installs the packages, checks the layout and the imports, validates the mod with Claude Code, type-checks it, lints it, and runs its tests. Each failure names its fix. [commands.md](commands.md) lists every step.

package/docs/install-steps.md

@@ -134,9 +134,9 @@ A mod that builds its own command-line program keeps its source in `cli/`, and c
    }
    ```
 
-   The program's name is the one `bin` command, or else `name`. A Rust program declares the same keys under `[package.metadata.cmod]` in `cli/Cargo.toml`.
+   The program's name is the one `bin` command, or else `name`. A Rust program declares the same keys under `[package.metadata.cmod]` in `cli/Cargo.toml`, and its name is the one `[[bin]]` `name`, or else the `[package]` `name`.
 
-2. The build writes one file per machine into `output`, each named `<program>-<os>-<arch>`, such as `hello-darwin-arm64`.
+2. The build writes one file per machine into `output`, each named `<program>-<os>-<arch>`, such as `hello-darwin-arm64`. cmod runs it with `CMOD_MACHINES` set to the machines it needs, separated by spaces: `cmod link` names this machine alone, and `cmod publish` names all four. A build that ignores `CMOD_MACHINES` and builds every machine works too, only slower to link. cmod takes only the files the build wrote in that run, so a build left from an earlier run is never released.
 
 3. The mod's own `package.json` names the program: `"cmod": { "program": "hello" }`. `.claude-plugin/plugin.json` names the GitHub `repository`.
 
@@ -145,7 +145,7 @@ Then:
 - `cmod link` builds the program and links this machine's build to `~/.local/bin/<program>`.
 - `cmod publish` builds every machine's file and attaches each to the GitHub release `v<version>`, with a `SHA256SUMS` file. It refuses a `cli/` program that the `package.json` `program` key does not name.
 - On install, cmod downloads `<repository>/releases/download/v<version>/<program>-<machine>`, checks it against `SHA256SUMS`, runs `<program> --version`, and links it to `~/.local/bin/<program>`.
-- cmod refuses to replace a `~/.local/bin/<program>` it did not make, and a program `PATH` already finds somewhere else.
+- cmod refuses to replace a `~/.local/bin/<program>` it did not make, and a program `PATH` finds in a folder ahead of `~/.local/bin`.
 - `cmod unlink` and the uninstall remove the program.
 
 The cmod repository ships the `cmod` program this way. Its `package.json` holds `"cmod": { "program": "cmod" }`, and its `cli/package.json` holds `"cmod": { "build": "bun run build", "output": "dist" }`.

package/docs/jobs.md

@@ -361,7 +361,7 @@ type JobContext<State> = {
 
 - `claude` reaches Claude Code itself. [The claude members](#the-claude-members) lists each one.
 - `claude.store` is where cmod saves `mod.state`, under keys that start with `<mod>.`, such as `<mod>.<key>`. A job of your own never writes those keys, or it changes the mod's state behind cmod's back.
-- `on` adds a Claude Code hook-module handler, `(e, next) => …`, on a `classic.<ModEvent>` event or on `tool.check`, `tool.call`, `prompt.submit`, `prompt.context`, `command.run`, `session.measure`, `skill.prompt`, `ui.render`, `ui.press`, `ui.close`, or `cmod.call`. The handler calls `next(e)` to pass the event on. A job with a handler on `tool.check`, `classic.PreToolUse`, or `classic.PermissionRequest` needs `registerPermissionCheck` in `hooks/register.ts` ([mod.md](mod.md)).
+- `on` adds a Claude Code hook-module handler, `(e, next) => …`, on a `classic.<ModEvent>` event or on `tool.check`, `tool.call`, `prompt.submit`, `prompt.context`, `command.run`, `session.measure`, `skill.prompt`, `ui.render`, `ui.press`, `ui.scroll`, `ui.close`, or `cmod.call`. The handler calls `next(e)` to pass the event on. A job with a handler on `tool.check` or `classic.PermissionRequest` needs `registerPermissionCheck` in `hooks/register.ts` ([mod.md](mod.md)).
 - `announce` adds a phrase to the list cmod logs when the mod first starts.
 - `reserveName` throws `taken` when the mod already reserved that `kind` and `name`. A job calls it to refuse a duplicate.
 - `toolCalls.agentOf(toolUseId)` resolves `{ agentId?, agentType? }`, the subagent behind a call.
@@ -405,12 +405,11 @@ Each member calls the member of the same name in Claude Code's hooks API, `$`, w
 | `ui.open(pane)` | Opens a pane, `{ id, title?, focus?, closeOnEscape?, holdToasts?, rows?, columns? }`, and resolves `{ isPlaced }`. |
 | `ui.close(pane)` | Closes the open pane with that `{ id }`. |
 | `ui.panes()` | The plugin's open panes: each one's id, title, and whether it is shown, holds the keyboard, and is placed. |
+| `ui.scroll(args)` | What `mod.ui.scroll` calls. |
 | `ui.resolve(e)` | The element table of the surface a `ui.render` event draws on. |
 | `process.run(argv, init?)` | Runs a program to its end. `mod.process.run` is built on it. |
 | `process.spawn(request)` | Starts a program and streams its output. `mod.process.spawn` is built on it. |
-| `fs.read`, `fs.write`, `fs.list` | What `mod.fs` calls. A relative path is under the session's working folder. |
-| `fs.exists(path)` | Resolves whether the path exists. |
-| `fs.stat(path, options?)` | Resolves `{ kind, size, mtimeMs, isLink }`, and `realPath` with `{ resolve: true }`. It rejects for a missing path. |
+| `fs.read`, `fs.write`, `fs.list`, `fs.exists`, `fs.stat` | What `mod.fs` calls. A relative path is under the session's working folder. |
 | `http.fetch(url, init?)` | What `mod.http.fetch` calls. |
 | `settings.read(args?)` | What `mod.settings.read` calls. |
 | `store.get`, `store.set`, `store.delete`, `store.keys` | The plugin's key-value store, where cmod also keeps `mod.state`. |
@@ -423,9 +422,11 @@ Each member calls the member of the same name in Claude Code's hooks API, `$`, w
 | `session.model()` | The main conversation's model, as `/model` shows it. |
 | `session.usage()` | When the session began, the context window's fill, the rate-limit windows, and the cost, as the status line has them. |
 | `session.surfaces()` | Every surface the session draws on, `terminal` first. Empty in a plain `-p` run. |
+| `session.messages(args?)` | What `mod.session.messages` calls. |
 | `command.register(spec)` | Adds a slash command. `slashCommand` is built on it. |
 | `tool.register(spec)` | Adds a tool. `tool` is built on it. |
 | `agent.list()` | The session's subagents and teammates so far. |
+| `agent.spawn(args)` | What `mod.agent.spawn` calls. |
 | `env.home()` | The `HOME` variable, or `undefined` when it is unset. |
 | `env.dataHome()` | The `XDG_DATA_HOME` variable, or `undefined`. |
 | `env.configHome()` | The `CLAUDE_CONFIG_DIR` variable, or `undefined`. |

package/docs/mod.md

@@ -51,7 +51,7 @@ When a step fails, the mod does not start. Its progress line above the prompt na
 - `its state did not load: <error>` when reading the saved values or a `state.json` fails.
 - `its setup function threw: <error>` when `setup` throws or rejects.
 - `its open panes did not load: <error>` when Claude Code cannot list the open panes.
-- `it decides permissions on <events>, so hooks/register.ts must call registerPermissionCheck(addHook) after registerMod` when `setup` adds a hook on `PreToolUse` or `PermissionRequest`, or a job that decides permissions, and `register.ts` does not register the permission check.
+- `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.`
 
@@ -74,9 +74,9 @@ registerMod<State>(addHook: On, definition: ModDefinition<State>): void
 registerPermissionCheck(addHook: On): void
 ```
 
-`registerMod` registers one handler per Claude Code event the mod can use, and routes each event to the mod. It leaves out Claude Code's permission check, the events `tool.check`, `PreToolUse`, and `PermissionRequest`.
+`registerMod` registers one handler per Claude Code event the mod can use, and routes each event to the mod. A `PreToolUse` hook runs on `tool.call`, which `registerMod` registers ([hooks.md](hooks.md)). It leaves out Claude Code's permission check, the events `tool.check` and `PermissionRequest`.
 
-A mod that decides permissions calls `registerPermissionCheck` after `registerMod`. That covers a hook on `PreToolUse` or `PermissionRequest`, the `permissions` job, and a job of your own on `tool.check`:
+A mod that decides permissions calls `registerPermissionCheck` after `registerMod`. That covers a `PreToolUse` hook that answers `permissionDecision: 'allow'` or `'ask'`, a hook on `PermissionRequest`, the `permissions` job, and a job of your own on `tool.check`:
 
 ```ts
 export function register(addHook: On): void {
@@ -102,11 +102,13 @@ type Mod<State> = {
   readonly cwd: string
   on(event, hook): void
   use(job): Handle
-  readonly ui: { pane, render, toast, progress, ask }
+  readonly ui: { pane, render, toast, progress, ask, scroll }
   readonly process: { run, spawn }
-  readonly fs: { read, write, list }
+  readonly fs: { read, write, list, exists, stat }
   readonly http: { fetch }
   readonly settings: { read }
+  readonly session: { messages }
+  readonly agent: { spawn }
   readonly dependencies: CmodDependencies
 }
 ```
@@ -120,11 +122,13 @@ type Mod<State> = {
 | `cwd` | The session's working folder. It follows a `cd` in a Bash or PowerShell call, and `/cd`. | |
 | `on` | Adds a hook on a Claude Code event. | [hooks.md](hooks.md) |
 | `use` | Adds a job, such as a slash command or a tool, and returns its handle. | [jobs.md](jobs.md) |
-| `ui` | Panes, slot renders, toasts, progress lines, and questions. | [ui.md](ui.md) |
+| `ui` | Panes, slot renders, toasts, progress lines, questions, and scrolling. | [ui.md](ui.md) |
 | `process` | Runs a program. | below |
-| `fs` | Reads and writes files. | below |
+| `fs` | Reads, writes, and looks up files. | below |
 | `http` | Fetches a URL. | below |
 | `settings` | Reads Claude Code's settings. | below |
+| `session` | Reads the conversation, or a subagent's. | below |
+| `agent` | Starts a subagent. | below |
 | `dependencies` | Calls the methods of other mods. | [dependencies.md](dependencies.md) |
 
 ### mod.process
@@ -168,12 +172,16 @@ export const branchNote = defineMod({
 mod.fs.read(path: string): Promise<string>
 mod.fs.write(path: string, text: string): Promise<void>
 mod.fs.list(path?: string): Promise<FsEntry[]>
+mod.fs.exists(path: string): Promise<boolean>
+mod.fs.stat(path: string, options?: { resolve: boolean }): Promise<FsStat>
 ```
 
 - A relative path is under the session's working folder. An absolute path is used as given. Text is UTF-8.
 - `read` rejects a missing file and a file over 4 MiB.
 - `write` writes the whole file and creates its folders.
 - `list` lists a folder, the working folder without a path. Each entry is `{ name, kind, size, mtimeMs, isLink }`, and `kind` is `'file'`, `'dir'`, or `'other'`. A symbolic link is `'other'` with `isLink` true.
+- `exists` answers whether the path leads to a file or a folder.
+- `stat` answers `{ kind, size, mtimeMs, isLink }` of what the path leads to, following a symbolic link, and rejects a missing path. With `{ resolve: true }` it also answers `realPath`: the absolute path, every symbolic link followed.
 
 A file the mod ships is under the plugin's folder. `mod` has no member that names that folder, so a job of your own reads it from `claude.plugin.root` ([jobs.md](jobs.md#the-claude-members)). A file the mod keeps for itself belongs in `mod.dataFolder`.
 
@@ -208,6 +216,48 @@ export const pluginCount = defineMod({
 })
 ```
 
+### mod.session
+
+```ts
+mod.session.messages(): Promise<SessionMessage[]>
+mod.session.messages(args: { agentId?: string; as?: 'api' }): Promise<…>
+```
+
+`messages` reads the main conversation, one `{ role, text, toolUses, toolResults }` entry per message. A message has no id of its own, and each tool use carries its `tool_use_id`. `{ agentId }` reads that subagent's conversation instead, the id a `SubagentStart` or `SubagentStop` hook gets as `agent_id`, and answers `{ deny }` when the session cannot read it, so `Array.isArray` tells the two apart. `{ as: 'api' }` reads it in the Messages API form, `{ role, content }` with the content blocks whole.
+
+```ts
+mod.on('SubagentStop', async ({ agent_id }) => {
+  const read = await mod.session.messages({ agentId: agent_id })
+  if (Array.isArray(read)) mod.ui.toast(read.at(-1)?.text ?? '')
+})
+```
+
+### mod.agent
+
+```ts
+mod.agent.spawn(args: { prompt: string; description?; subagentType?; model?; name?; cwd? }): Promise<AgentSpawnResult>
+```
+
+`spawn` starts a subagent in the background, the way the Agent tool starts one, and resolves `{ agentId, model }` once it started, or `{ deny }` when a hook refused it. It does not wait for the subagent to finish. `subagentType` names an agent type, such as `explorer`. `mod.session.messages({ agentId })` reads the subagent's conversation so far.
+
+The subagent's answer arrives on the mod's `SubagentStop` hook once it finishes: the input's `agent_id` is the `agentId` that `spawn` resolved, and its `last_assistant_message` is the subagent's final reply. A hook may wait for it, as this one does:
+
+```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', async (input) => {
+  if (!input.prompt.startsWith('/summarize')) return
+  const spawned = await mod.agent.spawn({ prompt: 'Summarize README.md in one line.', subagentType: 'Explore' })
+  if (spawned.agentId === undefined) return
+  const summary = await new Promise<string>((resolve) => answers.set(spawned.agentId as string, resolve))
+  return { hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: summary } }
+})
+```
+
 ## messageOf
 
 ```ts

package/docs/testing.md

@@ -58,7 +58,9 @@ type TestedMod<State> = {
   lines(slot, props, requestId?): Promise<string[]>
   type(line: string): Promise<Reply>
   callTool(name: string, input: Record<string, unknown>): Promise<EventResult<'tool.call'>>
-  press(paneId: string, key: string): Promise<void>
+  press(paneId: string, key: string, link?: string): Promise<void>
+  input(paneId: string, key: string, text: string, kind?: 'submit' | 'change'): Promise<void>
+  select(paneId: string, key: string, value: string): Promise<void>
   moveTo(projectRoot: string, cwd?: string): Promise<void>
   readonly state: Readonly<State>
   readonly calls: readonly TestCall[]
@@ -69,7 +71,7 @@ type TestedMod<State> = {
 
 ### start
 
-Starts the mod: loads its state, runs `setup`, and adds its hooks, panes, and jobs. `fire`, `lines`, `type`, `callTool`, `press`, and `moveTo` start the mod first, so a test calls `start` only before it reads `state` or `shown` with nothing else to run. It rejects with the reason when the mod does not start.
+Starts the mod: loads its state, runs `setup`, and adds its hooks, panes, and jobs. `fire`, `lines`, `type`, `callTool`, `press`, `input`, `select`, and `moveTo` start the mod first, so a test calls `start` only before it reads `state` or `shown` with nothing else to run. It rejects with the reason when the mod does not start.
 
 ### fire
 
@@ -80,9 +82,10 @@ fire<N extends RoutedEvent>(event: N, input: Args<N>, below?): Promise<EventResu
 
 - `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.
 - For a tool event, `files` is worked out from the call and the test's `files`, as in Claude Code.
-- `below` is what the hooks beneath the mod answered. Pass it to test how the mod's answer combines with another, such as a `deny` beneath. When nothing in the mod answers, `fire` returns `below` as it is.
+- `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, a `PreToolUse` decision is `allow: true`, or the key `ask` or `deny` with the reason as its value, and `decision: 'block'` is `block`.
+- It returns the combined answer in Claude Code's own field names: `additionalContext` is a list, and `decision: 'block'` is `block`.
 - `fire('tool.check', { tool: 'Edit', input: { … }, tool_use_id: 'toolu_1' }, { decision: 'allow' })` asks the mod's permission rules about any call. A name with a dot fires that Claude Code hook-module event as it is.
 
 ```ts
@@ -141,7 +144,7 @@ Waits until the work a hook started without awaiting it has run, such as a `void
 
 ### 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: false`, `bodyColumns`, `placement: 'dock'`, `scroll: { offset: 0, bodyRows: 24 }`, and `view: {}`, the main conversation's view.
+- `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.
 - `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.
 
 ```ts
@@ -169,9 +172,20 @@ test('the band shows the prompt count on its last line', async () => {
 
 `callTool(name, input)` runs the mod's permission rules on a call of its own tool, then the tool. `name` is the name given to `tool`, without `mcp__<plugin>__`. It returns `{ result }`, or `{ deny }` when a rule or the input check denies the call. It rejects a call a rule would ask the person about, and a tool the mod does not add.
 
-### press
+### press, input, and select
 
-`press(paneId, key)` presses the `Button` of an open pane whose `key` or `label` is `key`, and awaits its `onPress`.
+`press`, `input`, and `select` act on an element of an open pane as the person does, and await its handler. Each passes the handler the event Claude Code passes, with `component: 'Pane'`, `requestId` the pane's id, and `surface: 'terminal'`. Each rejects when the pane does not draw the element: `The pane "<pane>" of <mod> draws no <Element> with the key "<key>".`
+
+- `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.
+- `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
+await tested.input('history', 'search', 'deploy')
+await tested.select('history', 'agent', 'explorer')
+expect(await tested.lines('history')).toContain('deploy by explorer')
+```
 
 ### moveTo
 
@@ -193,8 +207,9 @@ type Fakes = {
   fs: { read?, write?, list?, exists?, stat? }
   http: { fetch? }
   settings: { read? }
-  ui: { ask?, open? }
-  agent: { list? }
+  ui: { ask?, open?, scroll? }
+  session: { messages? }
+  agent: { list?, spawn? }
   clock: { after?, every? }
   cmod: { call? }
 }
@@ -206,6 +221,7 @@ Set a fake to answer a call:
 - 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.
 - `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.
 
 ```ts