@cmodjs/core 0.1.7 → 0.1.9

package/docs/mod.md

@@ -17,7 +17,7 @@ type ModDefinition<State, Name> = {
 }
 ```
 
-- `name` is the mod's name. Use the `name` in `.claude-plugin/plugin.json`. Claude Mod Manager (CMod) keys the saved state and the `state.json` files by this name, and the data folder and the Skill overrides by the plugin's name, so the two must match. `defineMod` throws `defineMod: the mod needs a name, such as the name in .claude-plugin/plugin.json.` for a blank name.
+- `name` is the mod's name. Use the `name` in `.claude-plugin/plugin.json`. Claude Mod Manager (cmod) keys the saved state and the `state.json` files by this name, and the data folder and the Skill overrides by the plugin's name, so the two must match. `defineMod` throws `defineMod: the mod needs a name, such as the name in .claude-plugin/plugin.json.` for a blank name.
 - `state` holds the starting values, grouped by how long they last. [state.md](state.md) explains the groups.
 - `api` holds the methods other mods call. [dependencies.md](dependencies.md) explains it.
 - `setup` runs once when the mod starts. It adds hooks, panes, slot renders, and jobs. It may be `async`.
@@ -41,9 +41,9 @@ export const greeter = defineMod({
 
 ## When setup runs
 
-Claude Code loads the mod at the start of each session. CMod then checks that the mod is set up. A mod with an install step that has not run waits for the person's consent and the install first ([install-steps.md](install-steps.md)). Then CMod loads the saved state, runs `setup`, and marks as open each of the mod's panes that Claude Code already shows.
+Claude Code loads the mod at the start of each session. cmod then checks that the mod is set up. A mod with an install step that has not run waits for the person's consent and the install first ([install-steps.md](install-steps.md)). Then cmod loads the saved state, runs `setup`, and marks as open each of the mod's panes that Claude Code already shows.
 
-The first time a version starts, CMod shows the toast `<name> is ready` and logs `<name> added <what setup added>`, such as `the my-mod pane, a render of AbovePrompt and a hook on UserPromptSubmit`.
+The first time a version starts, cmod shows the toast `<name> is ready` and logs `<name> added <what setup added>`, such as `the my-mod pane, a render of AbovePrompt and a hook on UserPromptSubmit`.
 
 When a step fails, the mod does not start. Its progress line above the prompt names the failure and the fix:
 
@@ -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
 }
 ```
@@ -115,16 +117,18 @@ type Mod<State> = {
 | --- | --- | --- |
 | `name` | The mod's name from `defineMod`. | |
 | `state` | The mod's values. Assign to a key to change it. | [state.md](state.md) |
-| `dataFolder` | The mod's own folder in the CMod store: `$XDG_DATA_HOME/cmod/data/<plugin name>`, or `~/.local/share/cmod/data/<plugin name>` when `XDG_DATA_HOME` is not set. The install step gets the same folder as `CMOD_DATA`. CMod deletes it when the mod is removed. | [install-steps.md](install-steps.md) |
+| `dataFolder` | The mod's own folder in the cmod store: `$XDG_DATA_HOME/cmod/data/<plugin name>`, or `~/.local/share/cmod/data/<plugin name>` when `XDG_DATA_HOME` is not set. The install step gets the same folder as `CMOD_DATA`. cmod deletes it when the mod is removed. | [install-steps.md](install-steps.md) |
 | `projectRoot` | The project the session works in. It follows `/cd`. | |
 | `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
@@ -145,7 +149,7 @@ Both run a program without a shell. `argv[0]` is the program and the rest are it
 - `spawn` streams `{ stream: 'stdout' | 'stderr', text }` pieces as the program writes them. Its `result` resolves `{ code, signal }` once the stream is read to its end. Its first pull rejects when the program cannot start.
 - The `for await` loop over a `spawn` is the program's life. Leaving the loop, or calling `return()` on the stream, kills the program, and so does unloading the mod. Returning from the hook does not.
 
-Inside a job, CMod adds the job's deadline to each call ([jobs.md](jobs.md)).
+Inside a job, cmod adds the job's deadline to each call ([jobs.md](jobs.md)).
 
 ```ts
 import { defineMod } from '../node_modules/@cmodjs/core/mod.js'
@@ -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,30 @@ 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.
+
 ## messageOf
 
 ```ts

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 slot renders when one changes, and lets a person change the starting values without touching the mod's code.
 
 ## Declare the state
 
@@ -13,7 +13,7 @@
 | `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 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.
 
 Put values the mod works out again on every prompt, such as a git status, in `memory`.
 
@@ -56,7 +56,7 @@ A group other than `memory`, `session`, `project`, and `global` throws `<mod>: s
 
 ## Change a value
 
-Assign to a key. CMod saves the new value and redraws the mod.
+Assign to a key. cmod saves the new value and redraws the mod.
 
 - A key the state does not declare throws `<mod>: mod.state.<group>.<key> is not declared. Add it to state.<group> in defineMod with its starting value.`
 - 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:
@@ -75,8 +75,8 @@ export const reads = defineMod({
 })
 ```
 
-- Keep only JSON data in a saved group. A value CMod cannot save logs `<mod> could not keep state.<group>.<key>: <error>. Keep only JSON data in mod.state.`
-- CMod saves values one at a time in the order they were assigned.
+- Keep only JSON data in a saved group. A value cmod cannot save logs `<mod> could not keep state.<group>.<key>: <error>. Keep only JSON data in mod.state.`
+- cmod saves values one at a time in the order they were assigned.
 
 ## Where the values come from
 
@@ -87,7 +87,7 @@ When the mod starts, each value is, in order of precedence:
 3. The value in the person's own `state.json`.
 4. The starting value in `defineMod`.
 
-After a `/cd` to another project, CMod loads that project's `project` values and reads its `state.json` again.
+After a `/cd` to another project, cmod loads that project's `project` values and reads its `state.json` again.
 
 ## Let a person change the starting values
 
@@ -111,7 +111,7 @@ A `state.json` in either folder lists only the values to change:
 - A project `state.json` cannot set `global` values, because one repository cannot change a value for every project.
 - A file cannot set `memory` values.
 
-CMod ignores each entry it cannot use and logs one line naming the file, the entry, and the fix:
+cmod ignores each entry it cannot use and logs one line naming the file, the entry, and the fix:
 
 - a file that is not JSON, or not a JSON object
 - a group the mod does not declare
@@ -131,7 +131,7 @@ A person replaces the text of a Skill the mod ships by putting a file at the sam
 
 - Claude reads that file in place of the mod's from the next time the Skill loads, and updates of the mod keep it.
 - The project file wins over the person's file.
-- CMod drops the file's frontmatter, so the mod's own name and description stay.
+- cmod drops the file's frontmatter, so the mod's own name and description stay.
 - Only a Skill the mod ships in `skills/<skill>/` is replaced, and only when it loads as `<mod>:<skill>`.
 - Deleting the file brings the mod's text back.
 

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

package/docs/ui.md

@@ -8,9 +8,10 @@ mod.ui.render<S extends Slot>(slot: S, Component: (props: SlotProps<S>) => Rende
 mod.ui.toast(text: string): void
 mod.ui.progress<T>(title: string, task: (report: (step: ProgressStep) => void) => Promise<T>): Promise<T>
 mod.ui.ask(question: string, options?: readonly string[] | AskOptions): Promise<string>
+mod.ui.scroll(args: UiScrollArgs): Promise<UiScrollResult>
 ```
 
-Claude Mod Manager (CMod) draws the mod again whenever a value in `mod.state` changes. A render reads `mod.state` and returns what to show. It never draws by hand.
+Claude Mod Manager (cmod) draws the mod again whenever a value in `mod.state` changes. A render reads `mod.state` and returns what to show. It never draws by hand.
 
 ## Elements
 
@@ -46,7 +47,7 @@ export function Count({ label, count }: { readonly label: string; readonly count
 
 An element called outside a render throws `<Element> was called outside a render. Use it inside a pane's render or a slot's component.` So build elements inside a pane's `render` or a slot's component, never at module load or in a hook.
 
-`drawWith(table, draw, markdown?)` is the function CMod draws a render with. A mod never calls it.
+`drawWith(table, draw, markdown?)` is the function cmod draws a render with. A mod never calls it.
 
 ## Panes
 
@@ -62,14 +63,23 @@ type Pane<State> = {
   readonly title: string
   readonly columns?: number | ((state: State) => number | undefined)
   readonly rows?: number | ((state: State) => number | undefined)
+  readonly closeOnEscape?: true
+  readonly holdToasts?: true
   render(mod: Mod<State>, props: Frozen<RenderPropsOf['Pane']>): RenderElement
+  onScroll?(mod: Mod<State>, e: Frozen<UiScrollInput>): void | Promise<void>
+  onClose?(mod: Mod<State>, e: Frozen<PaneCloseInput>): void | Promise<void>
 }
 ```
 
 - `id` is 1 to 64 letters, digits, `_`, or `-`. Another id throws `definePane: "<id>" is not a pane id.`
 - `title` labels the pane's tab while more than one pane is open.
-- `columns` and `rows` ask for a size. A number must be a whole number above 0, or `definePane` throws. A function reads the state and returns the size, or `undefined` for Claude Code's default. When the state changes the size, CMod resizes an open pane. A function that returns a bad size keeps an open pane at its size and logs the pane's title to the debug log. `open`, and `toggle` on a closed pane, reject with that size instead.
+- `columns` and `rows` ask for a size. A number must be a whole number above 0, or `definePane` throws. A function reads the state and returns the size, or `undefined` for Claude Code's default. When the state changes the size, cmod resizes an open pane. A function that returns a bad size keeps an open pane at its size and logs the pane's title to the debug log. `open`, and `toggle` on a closed pane, reject with that size instead.
+- `closeOnEscape` closes the pane when the person presses Escape while it holds the keyboard, as their own close does. Left out, Escape gives the keyboard back to the prompt and the pane stays.
+- `holdToasts` holds every toast back while the pane is shown, the toasts of other plugins and of Claude Code included. Use it for a pane the person answers and closes, never for one that stays open.
 - `render` draws the pane's body. `props` holds `title`, `isFocused`, `bodyColumns`, `placement` (`'dock'` or `'inline'`), `scroll`, the body's window over a taller drawing, and `view`, which transcript is on screen beside the pane.
+- `onScroll` runs after this pane's window moved, by the person's wheel or keys or by `mod.ui.scroll`. `e` holds the new `offset`, the move's `by`, `bodyRows`, `contentRows`, and `origin`. Another pane's scroll and the band's never reach it, and a scroll Claude Code refused does not either.
+- `onClose` runs after the pane closed, by the person or by `close()`. `e.origin.kind` is `'person'` or `'plugin'`.
+- A handler that throws logs `<mod>: the <title> pane's <handler> threw: <error>`.
 
 Put each pane in its own file in `src/panes/`.
 
@@ -98,21 +108,23 @@ export const notesPane = definePane<NotesState>({
 
 ```ts
 type PaneHandle = {
-  open(): Promise<void>
+  open(options?: { readonly focus?: true }): Promise<void>
   close(): Promise<void>
-  toggle(): Promise<void>
+  toggle(options?: { readonly focus?: true }): Promise<void>
   readonly isOpen: boolean
 }
 ```
 
 - `open` asks Claude Code to show the pane. `isOpen` turns true once Claude Code places it. Claude Code may hold a pane back, and then `isOpen` stays false.
-- `mod.ui.pane` only adds the pane. CMod opens it only when the mod calls `open` or `toggle`, and Claude Code shows a pane only once the plugin has opened it. So give the person a way in, such as a slash command whose `reply` calls `pane.toggle()`.
+- `{ focus: true }` asks Claude Code to give the pane the keyboard as it opens. Claude Code gives it only while the prompt is empty and holds the keyboard, so typed text, a dialog, or another pane the person is using keeps it. cmod sends `focus` only on that one open, never when it resizes the pane.
+- `mod.ui.pane` only adds the pane. cmod opens it only when the mod calls `open` or `toggle`, and Claude Code shows a pane only once the plugin has opened it. So give the person a way in, such as a slash command whose `reply` calls `pane.toggle()`.
 - A pane opened from what the person did, such as a slash command they typed or a `Button` they pressed, shows at any terminal width. A pane opened from anything else, such as `setup`, a timer, or `SessionStart`, shows only on a terminal 144 columns wide, or 110 for a pane the person opened before. Below that it waits undrawn until the person opens it or the terminal widens.
 - `close` closes it. The person closes a pane too, and `isOpen` follows.
 - `toggle` closes an open pane and opens a closed one.
 - When the mod starts, `isOpen` is true for each of its panes Claude Code already shows.
 - Adding two panes with one id throws `<mod>: the pane "<id>" is already added. Give each pane its own id.`
-- The line CMod logs when the mod first starts names the pane by its `title`, as in `the Notes pane`.
+- A `render` that throws draws `The <title> pane could not draw: <error>` in the pane, and cmod logs `<mod>: the <title> pane render threw: <error>` once.
+- The line cmod logs when the mod first starts names the pane by its `title`, as in `the Notes pane`.
 
 ```tsx
 import { defineMod } from '../node_modules/@cmodjs/core/mod.js'
@@ -126,7 +138,7 @@ export const notes = defineMod({
   state: initialState,
   setup(mod) {
     const pane = mod.ui.pane(notesPane)
-    mod.use(slashCommand({ name: 'notes', description: 'Show or hide the notes', reply: () => pane.toggle() }))
+    mod.use(slashCommand({ name: 'notes', description: 'Show or hide the notes', reply: () => pane.toggle({ focus: true }) }))
   },
 })
 ```
@@ -157,7 +169,7 @@ export const notes = defineMod({
 - `Default` draws what Claude Code, and the renders of other mods, would draw. Pass it props to change what it draws, such as `<Default hint="…" />`. Return `<Default />` to change nothing.
 - A render adds to what it wraps. In `AbovePrompt`, drawing `<Default />` and a line under it keeps the lines of Claude Code and other mods.
 - A render must draw the same for the same props. One that calls `Default` a different number of times on a second draw falls back to Claude Code's drawing.
-- A render that throws falls back to Claude Code's drawing. CMod logs `<mod>: the <Slot> render threw, so Claude Code draws its own: <error>` once.
+- A render that throws falls back to Claude Code's drawing. cmod logs `<mod>: the <Slot> render threw, so Claude Code draws its own: <error>` once.
 - A mod renders each slot once. A second `mod.ui.render` of one slot throws `<mod>: a render of <Slot> is already added. Render each slot once.` For a markdown slot the error names it as `a render of markdown <Kind>`, such as `a render of markdown CodeBlock`.
 - `slots.ToolUse` changes a call's own row. A group of calls shows the `slots.ToolGroup` row, which Claude Code builds from the stored message, so a mod that hides a tool's input also sets `isExpanded` on `slots.ToolGroup` to unfold the group into `ToolUse` rows.
 - No slot covers the permission dialog.
@@ -290,6 +302,18 @@ export const committer = defineMod({
 })
 ```
 
+## Scrolling
+
+```ts
+mod.ui.scroll(args: { to: 'start' | 'end' | { key: string } | { requestId: string }; in?: string; block?: 'start' | 'center' | 'end' | 'nearest' }): Promise<UiScrollResult>
+```
+
+`scroll` brings something the mod drew into view. `{ key }` is an element the mod drew with that `key`. `'start'` and `'end'` are the top and bottom of the pane whose id `in` names, and `'end'` keeps up with rows the mod adds until the person scrolls. `{ requestId }` is a row Claude Code drew, such as a message of the transcript, which scrolls only while the mod answers the person's own press or key. `block` places the target in the window, `'nearest'` by default. It resolves `{}` once the window moved, or `{ deny }` with the reason it did not.
+
+```tsx
+<Button label="Latest" onPress={() => mod.ui.scroll({ to: 'end', in: 'log' })} />
+```
+
 ## Test the UI
 
 `tested.lines(paneId)` reads an open pane as rows of text. `tested.lines(slot, props)` draws a slot render. `tested.press(paneId, key)` presses a button. `tested.shown.toasts` lists the toasts. [testing.md](testing.md) covers each.

package/jobs/check.js

@@ -1,6 +1,6 @@
 import { longestMs } from '../runtime/deadline.js';
 import { callEffects } from '../utils/call-effects.js';
-import { parentOf } from '../utils/paths.js';
+import { dirname } from '../vendor.js';
 import { listed, messageOf } from '../utils/text.js';
 import { afterCall, modOf, targetWords } from './context.js';
 import { matchTarget, targetOf } from './permissions/match-target.js';
@@ -55,6 +55,6 @@ async function triggeredRun(after, run, use, workspace) {
             existing.push(path);
     const last = existing.at(-1);
     if (last !== undefined)
-        return { command: [...run, ...existing], folder: parentOf(last) };
+        return { command: [...run, ...existing], folder: dirname(last) };
     return commandFolder === undefined ? undefined : { command: [...run], folder: commandFolder };
 }

package/jobs/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/jobs/context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,WAAW,CAAA;AAEhD,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAItE,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAA;AACjE,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,qCAAqC,CAAA;AACtF,OAAO,EAAY,KAAK,MAAM,EAAE,MAAM,+BAA+B,CAAA;AAOrE,wBAAgB,eAAe,CAAC,EAAE,MAAM,EAAE,EAAE,UAAU,GAAG,MAAM,OAAO,CAAC,SAAS,CAAC,CAOhF;AAaD,wBAAgB,SAAS,CAAC,KAAK,SAAS,MAAM,EAC5C,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC,EACtB,YAAY,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,KAAK,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,EAChF,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,SAAS,MAAM,EAAE,GAC5C,IAAI,CAUN;AAMD,wBAAgB,KAAK,CAAC,KAAK,SAAS,MAAM,EAAE,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,CAEjM;AAED,wBAAgB,SAAS,CAAC,KAAK,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,UAAU,CAAC,KAAK,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,GAAE,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAyB,GAAG,GAAG,CAAC,KAAK,CAAC,CAwBvL;AAwBD,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CASlD"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/jobs/context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,WAAW,CAAA;AAEhD,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAItE,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAA;AACjE,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,qCAAqC,CAAA;AACtF,OAAO,EAAY,KAAK,MAAM,EAAE,MAAM,+BAA+B,CAAA;AAOrE,wBAAgB,eAAe,CAAC,EAAE,MAAM,EAAE,EAAE,UAAU,GAAG,MAAM,OAAO,CAAC,SAAS,CAAC,CAOhF;AAaD,wBAAgB,SAAS,CAAC,KAAK,SAAS,MAAM,EAC5C,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC,EACtB,YAAY,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,KAAK,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,EAChF,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,SAAS,MAAM,EAAE,GAC5C,IAAI,CAUN;AAMD,wBAAgB,KAAK,CAAC,KAAK,SAAS,MAAM,EAAE,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,CAEjM;AAED,wBAAgB,SAAS,CAAC,KAAK,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,UAAU,CAAC,KAAK,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,GAAE,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAyB,GAAG,GAAG,CAAC,KAAK,CAAC,CA0BvL;AAwBD,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CASlD"}

package/jobs/context.js

@@ -60,6 +60,8 @@ export function modWithin({ mod, claude }, deadline, workTree = async () => unde
             read: (path) => within('mod.fs.read', mod.fs.read(path)),
             write: (path, text) => within('mod.fs.write', mod.fs.write(path, text)),
             list: (path) => within('mod.fs.list', mod.fs.list(path)),
+            exists: (path) => within('mod.fs.exists', mod.fs.exists(path)),
+            stat: (path, options) => within('mod.fs.stat', mod.fs.stat(path, options)),
         },
         http: { fetch: (url, init) => within('mod.http.fetch', mod.http.fetch(url, init)) },
         dependencies: dependencyCalls(claude, within),

package/jobs/permissions/decide-permission.js

@@ -2,7 +2,7 @@ import { strictness } from '../../runtime/hooks.js';
 import { messageOf } from '../../utils/text.js';
 import { callBaseOf, callEffects } from '../../utils/call-effects.js';
 import { folderInScope, matchTarget, targetOf } from './match-target.js';
-import { resolvePath } from '../../utils/paths.js';
+import { resolve } from '../../vendor.js';
 const wordBoundary = '\\s;&|()<>\'"`=';
 export function stricterVerdict(first, second) {
     return strictness.indexOf(second.decision) > strictness.indexOf(first.decision) ? second : first;
@@ -63,7 +63,7 @@ async function unparsedMatches(target, use, effects, workspace) {
     const folder = named.length === 0 ? undefined : await folderInScope(shell, workspace);
     if (folder === undefined)
         return [];
-    return named.map((segment) => ({ call: { ...base, path: resolvePath(segment, folder) }, access: undefined, folder }));
+    return named.map((segment) => ({ call: { ...base, path: resolve(folder, segment) }, access: undefined, folder }));
 }
 function containsWord(line, word) {
     const escaped = word.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');

package/jobs/permissions/find-project-scope.d.ts

@@ -1,4 +1,4 @@
-import { type FileSystem } from '../../utils/paths.js';
+import type { FileSystem } from '../../utils/paths.js';
 export type ProjectScope = {
     workTreeOf: (path: string) => Promise<string | undefined>;
 };

package/jobs/permissions/find-project-scope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"find-project-scope.d.ts","sourceRoot":"","sources":["../../src/jobs/permissions/find-project-scope.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiC,KAAK,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAErF,MAAM,MAAM,YAAY,GAAG;IAAE,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;CAAE,CAAA;AAExF,MAAM,MAAM,SAAS,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,YAAY,GAAG,SAAS,CAAA;CAAE,CAAA;AAE3H,wBAAsB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,UAAU,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAwB1H"}
+{"version":3,"file":"find-project-scope.d.ts","sourceRoot":"","sources":["../../src/jobs/permissions/find-project-scope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAGtD,MAAM,MAAM,YAAY,GAAG;IAAE,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;CAAE,CAAA;AAExF,MAAM,MAAM,SAAS,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,YAAY,GAAG,SAAS,CAAA;CAAE,CAAA;AAE3H,wBAAsB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,UAAU,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAwB1H"}

package/jobs/permissions/find-project-scope.js

@@ -1,9 +1,9 @@
-import { nameOf, parentOf, resolvePath } from '../../utils/paths.js';
+import { basename, dirname, resolve } from '../../vendor.js';
 export async function findProjectScope(pluginRoot, home, fs) {
-    const skills = parentOf(pluginRoot);
-    const claude = parentOf(skills);
-    const root = parentOf(claude);
-    if (nameOf(skills) !== 'skills' || nameOf(claude) !== '.claude' || root === resolvePath(home, '/'))
+    const skills = dirname(pluginRoot);
+    const claude = dirname(skills);
+    const root = dirname(claude);
+    if (basename(skills) !== 'skills' || basename(claude) !== '.claude' || root === resolve('/', home))
         return undefined;
     const repositories = new Map();
     const repositoryOf = async (workTree) => {
@@ -20,7 +20,7 @@ export async function findProjectScope(pluginRoot, home, fs) {
         return undefined;
     return {
         async workTreeOf(path) {
-            for (let folder = path;; folder = parentOf(folder)) {
+            for (let folder = path;; folder = dirname(folder)) {
                 const repository = await repositoryOf(folder);
                 if (repository !== undefined)
                     return repository === project ? folder : undefined;
@@ -31,7 +31,7 @@ export async function findProjectScope(pluginRoot, home, fs) {
     };
 }
 async function readRepository(workTree, fs) {
-    const gitPath = resolvePath('.git', workTree);
+    const gitPath = resolve(workTree, '.git');
     const git = await fs.stat(gitPath).catch(() => undefined);
     if (git === undefined)
         return undefined;
@@ -41,8 +41,8 @@ async function readRepository(workTree, fs) {
         const gitDirectory = /^gitdir:\s*(.+)$/m.exec(await fs.read(gitPath))?.[1]?.trim();
         if (gitDirectory === undefined)
             throw new Error(`${gitPath} has no gitdir line.`);
-        const linkedDirectory = resolvePath(gitDirectory, workTree);
-        const commonDirectory = await fs.read(resolvePath('commondir', linkedDirectory)).then((text) => resolvePath(text.trim(), linkedDirectory), () => linkedDirectory);
+        const linkedDirectory = resolve(workTree, gitDirectory);
+        const commonDirectory = await fs.read(resolve(linkedDirectory, 'commondir')).then((text) => resolve(linkedDirectory, text.trim()), () => linkedDirectory);
         return (await fs.stat(commonDirectory)).realPath ?? commonDirectory;
     }
     catch {

package/jobs/permissions/match-target.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"match-target.d.ts","sourceRoot":"","sources":["../../src/jobs/permissions/match-target.ts"],"names":[],"mappings":"AAEA,OAAO,EAAc,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAE,KAAK,UAAU,EAAE,KAAK,QAAQ,EAAE,KAAK,QAAQ,EAAE,KAAK,OAAO,EAAE,MAAM,6BAA6B,CAAA;AACxL,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AAGxD,MAAM,MAAM,WAAW,GAAG;IAAE,OAAO,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAA;AACzI,MAAM,MAAM,SAAS,GAAG,MAAM,WAAW,CAAA;AACzC,MAAM,MAAM,QAAQ,CAAC,GAAG,SAAS,SAAS,IAAI,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC,CAAA;AAC9H,MAAM,MAAM,MAAM,GAAG;KAAG,GAAG,IAAI,SAAS,GAAG,QAAQ,CAAC,GAAG,CAAC;CAAE,CAAC,SAAS,CAAC,CAAA;AACrE,MAAM,MAAM,WAAW,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAI5F,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAQ/E;AAED,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CA6BlI;AA4BD,wBAAsB,aAAa,CAAC,KAAK,EAAE,WAAW,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAI/H"}
+{"version":3,"file":"match-target.d.ts","sourceRoot":"","sources":["../../src/jobs/permissions/match-target.ts"],"names":[],"mappings":"AAEA,OAAO,EAAc,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAE,KAAK,UAAU,EAAE,KAAK,QAAQ,EAAE,KAAK,QAAQ,EAAE,KAAK,OAAO,EAAE,MAAM,6BAA6B,CAAA;AACxL,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AAIxD,MAAM,MAAM,WAAW,GAAG;IAAE,OAAO,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAA;AACzI,MAAM,MAAM,SAAS,GAAG,MAAM,WAAW,CAAA;AACzC,MAAM,MAAM,QAAQ,CAAC,GAAG,SAAS,SAAS,IAAI,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC,CAAA;AAC9H,MAAM,MAAM,MAAM,GAAG;KAAG,GAAG,IAAI,SAAS,GAAG,QAAQ,CAAC,GAAG,CAAC;CAAE,CAAC,SAAS,CAAC,CAAA;AACrE,MAAM,MAAM,WAAW,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAI5F,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAQ/E;AAED,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CA6BlI;AA4BD,wBAAsB,aAAa,CAAC,KAAK,EAAE,WAAW,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAI/H"}

package/jobs/permissions/match-target.js

@@ -1,7 +1,8 @@
 import { matchesGlob } from '../../utils/matches-glob.js';
 import { parseShell } from '../../utils/parse-shell.js';
 import { callBaseOf } from '../../utils/call-effects.js';
-import { nameOf, realPathOf, relativePath } from '../../utils/paths.js';
+import { realPathOf, relativePath } from '../../utils/paths.js';
+import { basename } from '../../vendor.js';
 const targetKeys = ['command', 'read', 'write', 'fetch', 'subagent', 'tool'];
 export function targetOf(target) {
     const keys = targetKeys.filter((key) => key in target);
@@ -51,10 +52,10 @@ function commandPattern(pattern) {
     const command = parseShell(pattern).commands[0];
     if (command === undefined)
         throw new Error(`The command pattern '${pattern}' names no program.`);
-    return command;
+    return command.argv;
 }
 function commandMatches(pattern, argv) {
-    if (nameOf(argv[0]) !== nameOf(pattern[0]))
+    if (basename(argv[0]) !== basename(pattern[0]))
         return false;
     const wanted = splitArguments(pattern.slice(1));
     const actual = splitArguments(argv.slice(1));

package/mod.d.ts

@@ -1,4 +1,4 @@
-import type { AskOptions, ClassicHookInputs, CmodDependencies, FsEntry, HookStream, HttpInit, HttpResponse, PermissionRequestDecision, ProcessRunInit, ProcessRunResult, ProcessSpawnChunk, ProcessSpawnRequest, ProcessSpawnResult, RenderElement, Settings, SettingsReadArgs } from 'claude-code';
+import type { AgentSpawnArgs, AgentSpawnResult, AskOptions, ClassicHookInputs, CmodDependencies, FsEntry, FsStat, FsStatOptions, HookStream, HttpInit, HttpResponse, PaneOpenArgs, PermissionRequestDecision, ProcessRunInit, ProcessRunResult, ProcessSpawnChunk, ProcessSpawnRequest, ProcessSpawnResult, RenderElement, Settings, SettingsReadArgs, UiScrollArgs, UiScrollResult } from 'claude-code';
 import type { Claude } from './runtime/claude.js';
 import type { RoutedEvent } from './runtime/hooks.js';
 import type { RoutedHook } from './runtime/router.js';
@@ -11,16 +11,16 @@ export type ProgressStep = {
     readonly label?: string;
 };
 export type PaneHandle = {
-    open(): Promise<void>;
+    open(options?: Readonly<Pick<PaneOpenArgs, 'focus'>>): Promise<void>;
     close(): Promise<void>;
-    toggle(): Promise<void>;
+    toggle(options?: Readonly<Pick<PaneOpenArgs, 'focus'>>): Promise<void>;
     readonly isOpen: boolean;
 };
 export type { Claude, RoutedEvent, RoutedHook, ToolCalls };
 export { longestMs } from './runtime/deadline.js';
 export { notInstalled } from './runtime/dependencies.js';
 export { messageOf } from './utils/text.js';
-export type ModEvent = 'SessionStart' | 'SessionEnd' | 'UserPromptSubmit' | 'InstructionsLoaded' | 'PreToolUse' | 'PermissionRequest' | 'PermissionDenied' | 'PostToolUse' | 'PostToolUseFailure' | 'PostToolBatch' | 'SubagentStart' | 'SubagentStop' | 'Notification' | 'PreCompact' | 'Stop' | 'StopFailure' | 'CwdChanged';
+export type ModEvent = 'SessionStart' | 'SessionEnd' | 'UserPromptSubmit' | 'InstructionsLoaded' | 'PreToolUse' | 'PermissionRequest' | 'PermissionDenied' | 'PostToolUse' | 'PostToolUseFailure' | 'PostToolBatch' | 'SubagentStart' | 'SubagentStop' | 'Notification' | 'PreCompact' | 'Stop' | 'StopFailure' | 'CwdChanged' | 'FileChanged';
 export type HookAnswer = {
     continue?: boolean;
     stopReason?: string;
@@ -69,7 +69,8 @@ type HookInputs = Omit<ClassicHookInputs, 'PreToolUse' | 'PostToolUse' | 'PostTo
     };
     CwdChanged: Omit<ClassicHookInputs['CwdChanged'], 'transcript_path'>;
 };
-export type ModHook<E extends ModEvent> = (input: HookInputs[E]) => HookAnswer | void | Promise<HookAnswer | void>;
+export type HookInput<E extends ModEvent> = HookInputs[E];
+export type ModHook<E extends ModEvent> = (input: HookInput<E>) => HookAnswer | void | Promise<HookAnswer | void>;
 export type Mod<State extends object = Record<never, never>> = {
     readonly name: string;
     readonly state: Readonly<State>;
@@ -82,6 +83,7 @@ export type Mod<State extends object = Record<never, never>> = {
         toast(text: string): void;
         progress<T>(title: string, task: (report: (step: ProgressStep) => void) => Promise<T>): Promise<T>;
         ask(question: string, options?: readonly string[] | AskOptions): Promise<string>;
+        scroll(args: UiScrollArgs): Promise<UiScrollResult>;
     };
     readonly process: {
         run(argv: readonly string[], init?: ProcessRunInit): Promise<ProcessRunResult>;
@@ -91,6 +93,8 @@ export type Mod<State extends object = Record<never, never>> = {
         read(path: string): Promise<string>;
         write(path: string, text: string): Promise<void>;
         list(path?: string): Promise<FsEntry[]>;
+        exists(path: string): Promise<boolean>;
+        stat(path: string, options?: FsStatOptions): Promise<FsStat>;
     };
     readonly http: {
         fetch(url: string, init?: HttpInit): Promise<HttpResponse>;
@@ -98,6 +102,12 @@ export type Mod<State extends object = Record<never, never>> = {
     readonly settings: {
         read(args?: SettingsReadArgs): Promise<Settings>;
     };
+    readonly session: {
+        messages: Claude['session']['messages'];
+    };
+    readonly agent: {
+        spawn(args: AgentSpawnArgs): Promise<AgentSpawnResult>;
+    };
     readonly projectRoot: string;
     readonly cwd: string;
     readonly dependencies: CmodDependencies;