@cmodjs/core 0.3.0 → 1.5.0

package/src/records.ts

@@ -19,23 +19,31 @@ export type Steps = {
   permissions?: readonly string[]
 }
 
-export const listPermissions = ['network', 'run', 'files'] as const
-export const flagPermissions = ['conversation', 'prompt', 'model', 'agents', 'tools', 'config', 'approve'] as const
+export const listPermissions = ['network', 'run', 'files', 'config'] as const
+export const flagPermissions = ['conversation', 'prompt', 'model', 'tasks', 'tools', 'approve'] as const
 export type ListPermission = (typeof listPermissions)[number]
 export type FlagPermission = (typeof flagPermissions)[number]
 const permissionNames: readonly string[] = [...listPermissions, ...flagPermissions]
 const hostName = /^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?(\.[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?)*$/
 const programName = /^[A-Za-z0-9][A-Za-z0-9._+-]*$/
+const settingName = /^[A-Za-z][A-Za-z0-9]*$/
+const listItemHint: Readonly<Record<ListPermission, string>> = {
+  network: 'a host alone, such as "api.github.com", or a socket path, such as "/var/run/docker.sock"',
+  run: 'a program\'s command, such as "gh"',
+  files: 'a path that starts with ~/ or /, such as "~/.zshrc"',
+  config: 'a Claude Code setting\'s name, such as "cleanupPeriodDays"',
+}
 
 export type ReadFile = (path: string) => Promise<string | undefined>
 
 export type RunnerEvent =
-  | { kind: 'progress'; done: number; total: number; label: string }
-  | { kind: 'log'; text: string }
-  | { kind: 'needs-consent'; sha256: string; install: string; uninstall: string; keys: string; permissions: readonly string[] }
-  | { kind: 'done'; name: string; version?: string }
-  | { kind: 'missing'; name: string }
-  | { kind: 'failed'; code: number; message: string }
+  | { type: 'progress'; done: number; total: number; label: string }
+  | { type: 'log'; text: string }
+  | { type: 'needs-consent'; sha256: string; install: string; uninstall: string; keys: string; permissions: readonly string[] }
+  | { type: 'done'; name: string; version?: string }
+  | { type: 'missing'; name: string }
+  | { type: 'retries'; when: 'changed' | 'later' }
+  | { type: 'failed'; code: number; message: string }
 
 export const pluginName = /^[A-Za-z0-9][A-Za-z0-9._-]*$/
 
@@ -153,12 +161,12 @@ function readPermissions(steps: Record<string, unknown>): string[] {
       items.push('run:*')
       continue
     }
-    const example = name === 'network' ? '["api.github.com"]' : name === 'run' ? '["gh"], or "*" for any program' : '["~/.zshrc"]'
+    const example = { network: '["api.github.com"]', run: '["gh"], or "*" for any program', files: '["~/.zshrc"]', config: '["cleanupPeriodDays"]' }[name]
     if (!Array.isArray(value) || value.length === 0 || !value.every((each) => typeof each === 'string')) throw new Error(`${at} sets "${name}" to ${JSON.stringify(value)}. Write a list, such as "${name}": ${example}.`)
-    for (const each of value as string[]) {
+    for (const each of value) {
       const isPath = /^(~\/|\/)/.test(each) && !each.split('/').includes('..')
-      const isValid = name === 'network' ? hostName.test(each) || isPath : name === 'run' ? programName.test(each) : isPath
-      if (!isValid) throw new Error(`${at} lists "${each}" under "${name}". Write ${name === 'network' ? 'a host alone, such as "api.github.com", or a socket path, such as "/var/run/docker.sock"' : name === 'run' ? 'a program\'s command, such as "gh"' : 'a path that starts with ~/ or /, such as "~/.zshrc"'}.`)
+      const isValid = { network: hostName.test(each) || isPath, run: programName.test(each), files: isPath, config: settingName.test(each) }[name]
+      if (isValid !== true) throw new Error(`${at} lists "${each}" under "${name}". Write ${listItemHint[name as ListPermission]}.`)
       items.push(`${name}:${each}`)
     }
   }
@@ -176,17 +184,17 @@ export function permissionWords(item: string): string {
     case 'files':
       return `Change ${target}`
     case 'conversation':
-      return 'Read this conversation'
+      return 'Read your Claude Code conversations'
     case 'prompt':
       return 'Add text Claude reads and start turns'
     case 'model':
       return 'Ask a model, which uses your plan'
-    case 'agents':
-      return 'Start agents'
+    case 'tasks':
+      return 'Start tasks that work beside Claude'
     case 'tools':
       return "Use and change Claude's tool calls"
     case 'config':
-      return 'Change your Claude Code settings'
+      return `Change ${target} in your Claude Code settings`
     case 'approve':
       return "Approve Claude's tool calls for you"
     default:
@@ -196,6 +204,8 @@ export function permissionWords(item: string): string {
 
 export const settingsPagesMethod = 'cmod:settingsPages'
 
+export const changelogPage = 'changelog'
+
 export const openPageMethod = 'cmod:openPage'
 
 export const pendingStepsMethod = 'cmod:pendingSteps'
@@ -240,7 +250,10 @@ function readKeys(keys: unknown): Steps {
   return { keys: commands }
 }
 
+export const coreVersion = '1.5.0'
+
 export function oldestCmodFor(steps: Steps): string {
+  if (steps.permissions?.some((item) => item === 'tasks' || item.startsWith('config:')) === true) return '1.0.0'
   if (steps.permissions !== undefined) return '0.2.0'
   return Object.keys(steps.keys ?? {}).length > 0 ? '0.1.12' : '0.0.0'
 }
@@ -303,7 +316,7 @@ export async function scriptsSha256(steps: Steps, files: { read: ReadFile; list:
 }
 
 export function formatEvent(event: RunnerEvent): string {
-  switch (event.kind) {
+  switch (event.type) {
     case 'progress':
       return `progress ${event.done} ${event.total}${event.label === '' ? '' : ` ${event.label}`}`
     case 'log':
@@ -316,24 +329,28 @@ export function formatEvent(event: RunnerEvent): string {
       return `missing ${event.name}`
     case 'failed':
       return `failed ${event.code}\t${event.message.replace(/\s*\n\s*/g, ' ')}`
+    case 'retries':
+      return `retries ${event.when}`
   }
 }
 
 export function parseEvent(line: string): RunnerEvent {
   const progress = /^progress (\d+) (\d+)(?: (.*))?$/.exec(line)
-  if (progress !== null) return { kind: 'progress', done: Number(progress[1]), total: Number(progress[2]), label: progress[3] ?? '' }
+  if (progress !== null) return { type: 'progress', done: Number(progress[1]), total: Number(progress[2]), label: progress[3] ?? '' }
   const consent = /^needs-consent (\S+)\t([^\t]*)\t([^\t]*)(?:\t(.*))?$/.exec(line)
   if (consent !== null) {
     const [keys = '', ...permissions] = (consent[4] ?? '').split('\t')
-    return { kind: 'needs-consent', sha256: consent[1] as string, install: consent[2] as string, uninstall: consent[3] as string, keys, permissions: permissions.filter((item) => item !== '') }
+    return { type: 'needs-consent', sha256: consent[1] as string, install: consent[2] as string, uninstall: consent[3] as string, keys, permissions: permissions.filter((item) => item !== '') }
   }
   const done = /^done (\S+)(?: (\S+))?$/.exec(line)
-  if (done !== null) return { kind: 'done', name: done[1] as string, ...(done[2] === undefined ? {} : { version: done[2] }) }
+  if (done !== null) return { type: 'done', name: done[1] as string, ...(done[2] === undefined ? {} : { version: done[2] }) }
   const missing = /^missing (\S+)$/.exec(line)
-  if (missing !== null) return { kind: 'missing', name: missing[1] as string }
+  if (missing !== null) return { type: 'missing', name: missing[1] as string }
   const failed = /^failed (-?\d+)(?:\t(.*))?$/.exec(line)
-  if (failed !== null) return { kind: 'failed', code: Number(failed[1]), message: failed[2] ?? '' }
-  return { kind: 'log', text: line.replace(/^log /, '') }
+  if (failed !== null) return { type: 'failed', code: Number(failed[1]), message: failed[2] ?? '' }
+  const retries = /^retries (changed|later)$/.exec(line)
+  if (retries !== null) return { type: 'retries', when: retries[1] as 'changed' | 'later' }
+  return { type: 'log', text: line.replace(/^log /, '') }
 }
 
 export function isAtLeast(version: string, minimum: string): boolean {

package/src/register.ts

@@ -3,6 +3,7 @@ import type { ModDefinition } from './mod.js'
 import type { Options } from './options.js'
 import type { Claude } from './runtime/claude.js'
 import type { RoutedEvent } from './runtime/hooks.js'
+import { cmodPluginName } from './runtime/dependencies.js'
 import { createLifecycle, readPlugin, type Lifecycle } from './runtime/lifecycle.js'
 
 let lifecycle: Lifecycle<object>
@@ -19,7 +20,6 @@ async function startMod($: EngineInterface, eventInput: Frozen<Args<'session.sta
   const claude: Claude = {
     plugin: { name: $.plugin.name, root: $.plugin.root },
     ui: {
-      toast: (text, options) => $.ui.toast(text, options),
       status: (text) => $.ui.status(text),
       log: (text, options) => $.ui.log(text, options),
       notice: (toolUseId, text) => $.ui.notice(toolUseId, text),
@@ -29,6 +29,8 @@ async function startMod($: EngineInterface, eventInput: Frozen<Args<'session.sta
       close: (pane) => $.ui.close(pane),
       panes: () => $.ui.panes(),
       scroll: (args) => $.ui.scroll(args),
+      copy: (args) => $.ui.copy(args),
+      focus: (args) => $.ui.focus(args),
       resolve: (render) => $.ui.resolve(render),
     },
     process: {
@@ -65,11 +67,12 @@ async function startMod($: EngineInterface, eventInput: Frozen<Args<'session.sta
       surfaces: () => $.session.surfaces(),
       messages: ((args?: Parameters<Claude['session']['messages']>[0]) => (args === undefined ? $.session.messages() : $.session.messages(args))) as Claude['session']['messages'],
       append: (args) => $.session.append(args),
+      send: (args) => $.session.send(args),
     },
     prompt: { submit: (args) => $.prompt.submit(args) },
     model: { complete: (request, options) => $.model.complete(request, options) },
     command: { register: (command) => $.command.register(command) },
-    tool: { register: (tool) => $.tool.register(tool), call: ((input: ToolCallArgs) => $.tool.call(input)) as Claude['tool']['call'] },
+    tool: { register: (tool) => $.tool.register(tool), call: (input: ToolCallArgs) => $.tool.call(input) },
     agent: {
       list: () => $.agent.list(),
       spawn: (args) => $.agent.spawn(args),
@@ -81,34 +84,54 @@ async function startMod($: EngineInterface, eventInput: Frozen<Args<'session.sta
     },
     cmod: { call: (input) => $.cmod.call(input) },
   }
-  await lifecycle.start(claude, readPlugin)
-  return passOn(eventInput)
+  const [, answer] = await Promise.all([lifecycle.start(claude, readPlugin), passOn(eventInput)])
+  return answer
 }
 
 function routeToMod<N extends RoutedEvent>(_$: EngineInterface, eventInput: Frozen<Args<N>>, passOn: Next<N>): Promise<EventResult<N>> {
   return lifecycle.route(passOn.event, eventInput, (passed: unknown) => passOn(passed as Args<N>) as Promise<EventResult<N>>)
 }
 
+function routeCallToMod(_$: EngineInterface, eventInput: Frozen<Args<'cmod.call'>>, passOn: Next<'cmod.call'>): Promise<EventResult<'cmod.call'>> {
+  const called = { ...eventInput, caller: passOn.origin.plugin } as Frozen<Args<'cmod.call'>>
+  return lifecycle.route('cmod.call', called, (passed) => passOn(Object.fromEntries(Object.entries(passed).filter(([key]) => key !== 'caller')) as Args<'cmod.call'>))
+}
+
 export function registerMod<State extends object, Declared extends Options>(addHook: On, definition: ModDefinition<State, string, Declared>, options: PluginOptions): void {
   checksPermissions = false
   registered = definition as ModDefinition<object>
   lifecycle = createLifecycle(definition, () => checksPermissions, options)
   addHook('session.start', startMod)
+  addHook('classic.Setup', routeToMod)
   addHook('classic.SessionStart', routeToMod)
   addHook('classic.SessionEnd', routeToMod)
   addHook('classic.UserPromptSubmit', routeToMod)
+  addHook('classic.UserPromptExpansion', routeToMod)
   addHook('classic.InstructionsLoaded', routeToMod)
+  addHook('classic.ConfigChange', routeToMod)
+  addHook('classic.DirectoryAdded', routeToMod)
+  addHook('classic.PreModelSwitch', routeToMod)
+  addHook('classic.PostModelSwitch', routeToMod)
   addHook('classic.PermissionDenied', routeToMod)
   addHook('classic.PostToolUse', routeToMod)
   addHook('classic.PostToolUseFailure', routeToMod)
   addHook('classic.PostToolBatch', routeToMod)
+  addHook('classic.MessageDisplay', routeToMod)
   addHook('classic.SubagentStart', routeToMod)
   addHook('classic.SubagentStop', routeToMod)
+  addHook('classic.TaskCreated', routeToMod)
+  addHook('classic.TaskCompleted', routeToMod)
+  addHook('classic.TeammateIdle', routeToMod)
+  addHook('classic.Elicitation', routeToMod)
+  addHook('classic.ElicitationResult', routeToMod)
   addHook('classic.Notification', routeToMod)
   addHook('classic.PreCompact', routeToMod)
+  addHook('classic.PostCompact', routeToMod)
   addHook('classic.Stop', routeToMod)
   addHook('classic.StopFailure', routeToMod)
   addHook('classic.FileChanged', routeToMod)
+  addHook('classic.WorktreeCreate', routeToMod)
+  addHook('classic.WorktreeRemove', routeToMod)
   addHook('tool.call', routeToMod)
   addHook('prompt.submit', routeToMod)
   addHook('prompt.context', routeToMod)
@@ -119,7 +142,13 @@ export function registerMod<State extends object, Declared extends Options>(addH
   addHook('ui.press', routeToMod)
   addHook('ui.scroll', routeToMod)
   addHook('ui.close', routeToMod)
-  addHook('cmod.call', routeToMod)
+  addHook('cmod.call', routeCallToMod)
+  if (definition.name !== cmodPluginName) return
+  addHook('session.append', routeToMod)
+  addHook('session.compact', routeToMod)
+  addHook('session.receive', routeToMod)
+  addHook('agent.spawn', routeToMod)
+  addHook('prompt.attachment', routeToMod)
 }
 
 export function registerPermissionCheck(addHook: On): void {

package/src/runtime/announce.ts

@@ -0,0 +1,76 @@
+import { changelogPage, isObject, marketplaceOf, permissionWords } from '../records.js'
+import { changeLines, changelogSections, unreleased } from '../utils/changelog.js'
+import { ifMissing } from '../utils/paths.js'
+import { listed } from '../utils/text.js'
+import type { Claude } from './claude.js'
+import { cmodPluginName } from './dependencies.js'
+import type { Plugin } from './lifecycle.js'
+
+export type Announced = { readonly version: string; readonly added: readonly string[] }
+
+export type Announcement = { readonly message: string; readonly description?: string; readonly action?: { readonly label: string; readonly onClick: () => unknown } }
+
+export const announcementMs = 10_000
+
+const shownChanges = 3
+
+export function announcedOf(saved: unknown): Announced | undefined {
+  if (typeof saved === 'string') return { version: saved, added: [] }
+  if (!isObject(saved) || typeof saved['version'] !== 'string') return undefined
+  return { version: saved['version'], added: Array.isArray(saved['added']) ? saved['added'].map(String) : [] }
+}
+
+export async function announcementOf(claude: Claude, plugin: Plugin, granted: ReadonlySet<string>, added: readonly string[], previous: Announced | undefined): Promise<Announcement> {
+  const read = (path: string) => claude.fs.read(`${plugin.root}/${path}`).catch(ifMissing(undefined))
+  const manifest = jsonOf(await read('.claude-plugin/plugin.json'))
+  const field = (key: string) => (isObject(manifest) && typeof manifest[key] === 'string' ? manifest[key] : undefined)
+  const open = (page?: string) => () => claude.cmod.call({ to: cmodPluginName, method: 'openSettings', input: { mod: plugin.name, ...(page === undefined ? {} : { page }) } })
+  if (previous === undefined) {
+    const { program, keys } = plugin.steps
+    const rules = (await claude.fs.list(`${plugin.root}/rules`).catch(ifMissing([]))).filter((entry) => entry.kind === 'file' && entry.name.endsWith('.md')).map((entry) => entry.name.slice(0, -'.md'.length)).toSorted()
+    const lines = [
+      field('description'),
+      added.length > 0 ? `Adds ${listed(added)}.` : undefined,
+      rules.length > 0 ? `Adds ${rules.length} ${rules.length === 1 ? 'rule' : 'rules'}: ${listed(rules)}.` : undefined,
+      program === undefined ? undefined : `Installed the ${program} program.`,
+      ...Object.entries(keys ?? {}).map(([key, command]) => `Binds ${key} to /${command}.`),
+      ...[...granted].map((item) => `${permissionWords(item)}.`),
+    ]
+    return { message: 'Installed', ...described(lines), action: { label: 'Settings', onClick: open() } }
+  }
+  const version = plugin.version ?? ''
+  const isCheckout = marketplaceOf(plugin.root, plugin.name) === undefined
+  const sections = changelogSections((await read('CHANGELOG.md')) ?? '')
+  const section = sections.find((each) => each.version === version) ?? (isCheckout ? sections.find((each) => each.version === unreleased) : undefined)
+  const changes = section === undefined ? [] : changeLines(section.text)
+  const nowAdded = added.filter((each) => !previous.added.includes(each))
+  const gone = previous.added.filter((each) => !added.includes(each))
+  const fallback = previous.added.length === 0 ? [] : [nowAdded.length > 0 ? `Now adds ${listed(nowAdded)}.` : undefined, gone.length > 0 ? `No longer adds ${listed(gone)}.` : undefined]
+  const home = await claude.env.home()
+  const folder = home !== undefined && plugin.root.startsWith(`${home}/`) ? `~${plugin.root.slice(home.length)}` : plugin.root
+  const repository = field('repository')
+  const lines = [
+    ...(changes.length === 0 ? fallback : changes.length > shownChanges ? [...changes.slice(0, shownChanges), '…'] : changes),
+    `From ${previous.version}${isCheckout ? `, loaded from ${folder}` : ''}.`,
+    repository === undefined || isCheckout ? undefined : `Release notes: ${repository.replace(/\/$/, '')}/releases/tag/v${version}`,
+  ]
+  return {
+    message: `Updated to ${version}`,
+    ...described(lines),
+    ...(sections.length > 0 ? { action: { label: 'Changelog', onClick: open(changelogPage) } } : {}),
+  }
+}
+
+function jsonOf(text: string | undefined): unknown {
+  try {
+    return text === undefined ? undefined : JSON.parse(text)
+  } catch (error) {
+    if (error instanceof SyntaxError) return undefined
+    throw error
+  }
+}
+
+function described(lines: readonly (string | undefined)[]): { readonly description?: string } {
+  const kept = lines.filter((line) => line !== undefined)
+  return kept.length === 0 ? {} : { description: kept.join('\n') }
+}

package/src/runtime/before.ts

@@ -0,0 +1,200 @@
+import type { Args, Frozen } from 'claude-code'
+import type { Disposable } from '../mod.js'
+import { ContextEnd } from '../session/context/context.js'
+import { Document } from '../session/context/turn/message/document.js'
+import { Message, messagesOf, rowOfAppend, withTexts, type Unplaced } from '../session/context/turn/message/message.js'
+import { Note } from '../session/context/turn/message/note.js'
+import { Notice } from '../session/context/turn/message/notice.js'
+import { Prompt } from '../session/context/turn/message/prompt.js'
+import { Reply } from '../session/context/turn/message/reply.js'
+import { senderOf } from '../session/context/turn/message/sender.js'
+import { Skill } from '../session/context/turn/message/skill.js'
+import { ToolCall } from '../session/context/turn/message/tool-call.js'
+import { ToolResult } from '../session/context/turn/message/tool-result.js'
+import { TurnEnd } from '../session/context/turn/turn.js'
+import type { ConversationState, SessionChange, TaskData } from '../session/conversation.js'
+import { TaskEnd, TaskStart } from '../session/goal/task.js'
+import type { BeforeEvent } from '../session/session.js'
+import type { Claude } from './claude.js'
+import { cmodPluginName } from './dependencies.js'
+import type { Router } from './router.js'
+import { toolInputOf } from './tool-calls.js'
+
+export type Place = Pick<ConversationState, 'session' | 'context' | 'contextOpenedAt' | 'turn' | 'tasks' | 'taskTurns'>
+
+export type Decide = (event: BeforeEvent, change: SessionChange) => Promise<Partial<Answers> | undefined>
+
+export type Answers = { readonly text: string; readonly refuse: string; readonly input: Readonly<Record<string, unknown>>; readonly result: string; readonly owner: { readonly model: string } }
+
+export type BeforeHooks = { readonly place: () => Promise<Place>; readonly wants: (event: BeforeEvent) => Promise<boolean>; readonly decide: Decide }
+
+const appended: readonly BeforeEvent[] = [Note, Reply, ToolResult, Notice]
+
+const relayTag = /^(?:<cross-session-message[^>]*>\s*)?<cmod-relay>([\s\S]*)<\/cmod-relay>(?:\s*<\/cross-session-message>[\s\S]*)?$/
+
+export function relayOf(e: Frozen<Args<'session.receive'>>): string | undefined {
+  const isFromCmod = e.origin.kind === 'peer' && !('teammate' in e.origin) && e.origin.plugin === cmodPluginName
+  return isFromCmod ? relayTag.exec(e.text)?.[1] : undefined
+}
+
+export function installBefore({ claude, router, hooks }: { readonly claude: Claude; readonly router: Router; readonly hooks: BeforeHooks }): Disposable {
+  const { place, wants, decide } = hooks
+  const now = () => new Date().toISOString()
+  const asked = async (event: BeforeEvent, change: SessionChange) => (await decide(event, change)) ?? {}
+  const message = (where: Place, unplaced: Unplaced, task: string | undefined, isInTurn = true): SessionChange => {
+    const turn = isInTurn ? (task === undefined ? where.turn : where.taskTurns[task]) : undefined
+    const context = task === undefined ? where.context : (where.tasks[task]?.context ?? where.context)
+    return { type: Message, message: { ...unplaced, session: where.session, context, ...(turn === undefined ? {} : { turn: turn.prompt.id }), ...(task === undefined ? {} : { task }) } as Message }
+  }
+  const added: Disposable[] = [
+    router.add('prompt.submit', async (e, next) => {
+      if (!(await wants(Prompt)) || e.text.startsWith('/')) return next(e)
+      const where = await place()
+      const answer = await asked(Prompt, message(where, { id: '', at: now(), type: Prompt, text: e.text, from: senderOf(e.origin, false) }, undefined, false))
+      if (answer.refuse !== undefined) return { drop: answer.refuse }
+      return next(answer.text === undefined ? e : { ...e, text: answer.text })
+    }),
+    router.add('command.run', async (e, next) => {
+      if (!(await wants(Prompt))) return next(e)
+      const typed = e.args === '' ? `/${e.command}` : `/${e.command} ${e.args}`
+      const where = await place()
+      const answer = await asked(Prompt, message(where, { id: '', at: now(), type: Prompt, text: typed, from: senderOf(e.origin, false) }, undefined, false))
+      if (answer.refuse !== undefined) return { text: answer.refuse }
+      if (answer.text === undefined || answer.text === typed) return next(e)
+      const same = new RegExp(`^/${e.command}(?:\\s+|$)`).exec(answer.text)
+      if (same !== null) return next({ ...e, args: answer.text.slice(same[0].length) })
+      void claude.prompt.submit({ text: answer.text })
+      return {}
+    }),
+    router.add('session.receive', async (e, next) => {
+      if (!(await wants(Prompt)) || relayOf(e) !== undefined) return next(e)
+      const where = await place()
+      const answer = await asked(Prompt, message(where, { id: '', at: now(), type: Prompt, text: e.text, from: { type: 'session' } }, e.agentId, false))
+      if (answer.refuse !== undefined) return { consumed: answer.refuse }
+      return next(answer.text === undefined ? e : { ...e, text: answer.text })
+    }),
+    router.add('skill.prompt', async (e, next) => {
+      if (!(await wants(Skill))) return next(e)
+      const where = await place()
+      const answer = await asked(Skill, message(where, { id: '', at: now(), type: Skill, name: e.skill, text: e.text }, undefined))
+      return answer.text === undefined ? next(e) : { text: answer.text }
+    }),
+    router.add('prompt.attachment', async (e, next) => {
+      if (!(await wants(Document)) || e.type !== 'nested_memory') return next(e)
+      const where = await place()
+      const path = /^Contents of (.+?) \(/.exec(e.text)?.[1] ?? ''
+      const answer = await asked(Document, message(where, { id: '', at: now(), type: Document, path, text: e.text }, e.agentId))
+      if (answer.refuse !== undefined) return { text: null }
+      return answer.text === undefined ? next(e) : { text: answer.text }
+    }),
+    router.add('session.append', async (e, next) => {
+      const wanted = new Set((await Promise.all(appended.map(async (event) => ((await wants(event)) ? [event] : [])))).flat())
+      if (wanted.size === 0) return next(e)
+      const row = rowOfAppend({ uuid: e.uuid, door: e.door, origin: e.origin, message: e.message }, now(), '')
+      const found = messagesOf(row, e.agentId !== undefined)
+      if (!found.some((each) => wanted.has(each.type))) return next(e)
+      const where = await place()
+      const texts = new Map<number, string>()
+      for (const [part, unplaced] of found.entries()) {
+        if (!wanted.has(unplaced.type)) continue
+        const answer = await asked(unplaced.type, message(where, unplaced, e.agentId))
+        if (answer.text !== undefined) texts.set(part, answer.text)
+      }
+      return next(texts.size === 0 ? e : { ...e, message: { ...e.message, content: withTexts(row, texts) as typeof e.message.content } })
+    }),
+    router.add('tool.call', async (e, next) => {
+      if (!(await wants(ToolCall))) return next(e)
+      const where = await place()
+      const input = toolInputOf(e)
+      const answer = await asked(ToolCall, message(where, { id: e.tool_use_id, at: now(), type: ToolCall, callId: e.tool_use_id, name: e.tool, input, cwd: await claude.session.cwd() }, e.agentId))
+      if (answer.refuse !== undefined) return { deny: answer.refuse }
+      if (answer.result !== undefined) return { result: answer.result }
+      if (answer.input === undefined) return next(e)
+      const reserved = Object.fromEntries(Object.entries(e).filter(([key]) => !(key in input)))
+      return next({ ...reserved, ...answer.input } as Frozen<Args<'tool.call'>>)
+    }),
+    router.add('agent.spawn', async (e, next) => {
+      if (!(await wants(TaskStart))) return next(e)
+      const where = await place()
+      const task: TaskData = { id: '', title: e.description, agentType: e.subagentType, model: e.model ?? e.parentModel, openedBy: e.tool_use_id, openedAt: now(), ...(e.parentAgentId === undefined ? {} : { parent: e.parentAgentId }) }
+      const answer = await asked(TaskStart, { type: TaskStart, task: { ...task, context: where.context } })
+      if (answer.refuse !== undefined) return { deny: answer.refuse }
+      return next(answer.owner === undefined ? e : { ...e, model: answer.owner.model })
+    }),
+    router.add('classic.SubagentStop', async (e, next) => {
+      if (!(await wants(TaskEnd)) && !(await wants(TurnEnd))) return next(e)
+      const where = await place()
+      const task = where.tasks[e.agent_id]
+      if (task === undefined) return next(e)
+      const turn = where.taskTurns[e.agent_id]
+      const ending = (await wants(TaskEnd)) ? await asked(TaskEnd, { type: TaskEnd, task: { ...task, closedAt: now() } }) : {}
+      const refuse = ending.refuse ?? ((await wants(TurnEnd)) && turn !== undefined ? (await asked(TurnEnd, { type: TurnEnd, turn: { ...turn, closedAt: now() } })).refuse : undefined)
+      const below = await next(e)
+      return refuse === undefined ? below : { ...below, block: refuse }
+    }),
+    router.add('classic.Stop', async (e, next) => {
+      if (!(await wants(TurnEnd))) return next(e)
+      const where = await place()
+      if (where.turn === undefined) return next(e)
+      const answer = await asked(TurnEnd, { type: TurnEnd, turn: { ...where.turn, closedAt: now() } })
+      const below = await next(e)
+      return answer.refuse === undefined ? below : { ...below, block: answer.refuse }
+    }),
+    router.add('session.compact', async (e, next) => {
+      if (!(await wants(ContextEnd)) || e.trigger === 'precompute') return next(e)
+      const where = await place()
+      const task = e.agentId === undefined ? undefined : where.tasks[e.agentId]
+      if (e.agentId !== undefined && task === undefined) return next(e)
+      const context = task === undefined ? { number: where.context, openedAt: where.contextOpenedAt } : { number: task.context, openedAt: task.contextOpenedAt ?? task.openedAt, task: task.id }
+      const answer = await asked(ContextEnd, { type: ContextEnd, context: { ...context, closedAt: now() } })
+      return answer.refuse === undefined ? next(e) : { skip: answer.refuse }
+    }),
+  ]
+  return { dispose: () => added.forEach((each) => each.dispose()) }
+}
+
+export function withAnswer(change: SessionChange, answer: Partial<Answers>): SessionChange {
+  if (change.type === Message && answer.text !== undefined) return { ...change, message: { ...change.message, text: answer.text } as Message }
+  if (change.type === Message && answer.input !== undefined && change.message.type === ToolCall) return { ...change, message: { ...change.message, input: answer.input } }
+  if (change.type === TaskStart && answer.owner !== undefined) return { ...change, task: { ...change.task, model: answer.owner.model } }
+  return change
+}
+
+export async function foldAnswers(event: BeforeEvent, change: SessionChange, askers: readonly ((change: SessionChange) => Promise<unknown>)[], report: (error: unknown) => void): Promise<Partial<Answers> | undefined> {
+  let latest = change
+  let result: Partial<Answers> | undefined
+  for (const ask of askers) {
+    try {
+      const answer = answerOf(event, await ask(latest))
+      if (answer === undefined) continue
+      result = { ...result, ...answer }
+      if (answer.refuse !== undefined || answer.result !== undefined) return result
+      latest = withAnswer(latest, answer)
+    } catch (error) {
+      report(error)
+    }
+  }
+  return result
+}
+
+export function answerOf(event: BeforeEvent, answer: unknown): Partial<Answers> | undefined {
+  if (typeof answer !== 'object' || answer === null) return undefined
+  const given = answer as Partial<Answers>
+  const allowed: Readonly<Record<BeforeEvent, readonly (keyof Answers)[]>> = {
+    prompt: ['text', 'refuse'],
+    note: ['text'],
+    skill: ['text'],
+    document: ['text', 'refuse'],
+    reply: ['text'],
+    toolCall: ['input', 'result', 'refuse'],
+    toolResult: ['text'],
+    notice: ['text'],
+    taskStart: ['owner', 'refuse'],
+    taskEnd: ['refuse'],
+    turnEnd: ['refuse'],
+    contextEnd: ['refuse'],
+  }
+  const unread = Object.keys(given).filter((key) => !allowed[event].includes(key as keyof Answers))
+  if (unread.length > 0) throw new Error(`a before(${event}) listener answered ${unread.join(' and ')}, which ${event} does not take. It takes ${allowed[event].map((key) => `{ ${key} }`).join(', ')}.`)
+  return given
+}

package/src/runtime/bound.ts

@@ -0,0 +1,12 @@
+import type { Imports } from '../mod.js'
+
+let current: Imports | undefined
+
+export function bind(imports: Imports): void {
+  current = imports
+}
+
+export function bound(): Imports {
+  if (current === undefined) throw new Error("A mod's imports work once its setup runs. Call them from setup or from a hook, never at the top of a module.")
+  return current
+}

package/src/runtime/claude.ts

@@ -28,8 +28,11 @@ import type {
   Settings,
   SettingsReadArgs,
   Timer,
-  ToastOptions,
   ToolSpec,
+  UiCopyArgs,
+  UiFocusArgs,
+  UiFocusResult,
+  UiCopyResult,
   UiLogOptions,
   UiOpenResult,
   UiPane,
@@ -40,7 +43,6 @@ import type {
 export type Claude = {
   readonly plugin: { readonly name: string; readonly root: string }
   readonly ui: {
-    toast(text: string, options?: ToastOptions): void
     status(text: string | undefined): void
     log(text: string, options?: UiLogOptions): void
     notice(toolUseId: string, text: string | undefined): void
@@ -50,6 +52,8 @@ export type Claude = {
     close(pane: PaneCloseArgs): Promise<void>
     panes(): Promise<readonly UiPane[]>
     scroll(args: UiScrollArgs): Promise<UiScrollResult>
+    copy(args: UiCopyArgs): Promise<UiCopyResult>
+    focus(args: UiFocusArgs): Promise<UiFocusResult>
     resolve(e: ResolveInput): ElementTable<RenderSurface>
   }
   readonly process: {
@@ -86,6 +90,7 @@ export type Claude = {
     surfaces(): Promise<readonly RenderSurface[]>
     messages: EngineInterface['session']['messages']
     append: EngineInterface['session']['append']
+    send: EngineInterface['session']['send']
   }
   readonly prompt: { submit: EngineInterface['prompt']['submit'] }
   readonly model: { complete: EngineInterface['model']['complete'] }