@cmodjs/core 0.1.8 → 0.1.9

package/src/jobs/permissions/decide-permission.ts

@@ -3,7 +3,7 @@ import { messageOf } from '../../utils/text.js'
 import { callBaseOf, callEffects, type CallEffects, type ToolCall, type ToolUse } from '../../utils/call-effects.js'
 import type { Workspace } from './find-project-scope.js'
 import { folderInScope, matchTarget, targetOf, type MatchedCall, type Target, type TargetCalls, type TargetKey, type TargetOf } from './match-target.js'
-import { resolvePath } from '../../utils/paths.js'
+import { resolve } from '../../vendor.js'
 
 export type Rule<Mod> = {
   [Key in TargetKey]: TargetOf<Key> & {
@@ -71,7 +71,7 @@ async function unparsedMatches(target: Target, use: ToolUse, effects: CallEffect
   const named = patterns.map((pattern) => pattern.slice(pattern.lastIndexOf('/') + 1)).filter((segment) => segment !== '' && !/[*?[\]{}]/.test(segment) && line.includes(segment.toLowerCase()))
   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: string, word: string): boolean {

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

@@ -1,14 +1,15 @@
-import { nameOf, parentOf, resolvePath, type FileSystem } from '../../utils/paths.js'
+import type { FileSystem } from '../../utils/paths.js'
+import { basename, dirname, resolve } from '../../vendor.js'
 
 export type ProjectScope = { workTreeOf: (path: string) => Promise<string | undefined> }
 
 export type Workspace = { projectRoot: string; cwd: string; home: string; fs: FileSystem; scope: ProjectScope | undefined }
 
 export async function findProjectScope(pluginRoot: string, home: string, fs: FileSystem): Promise<ProjectScope | undefined> {
-  const skills = parentOf(pluginRoot)
-  const claude = parentOf(skills)
-  const root = parentOf(claude)
-  if (nameOf(skills) !== 'skills' || nameOf(claude) !== '.claude' || root === resolvePath(home, '/')) return undefined
+  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<string, string>()
   const repositoryOf = async (workTree: string) => {
     const known = repositories.get(workTree)
@@ -21,7 +22,7 @@ export async function findProjectScope(pluginRoot: string, home: string, fs: Fil
   if (project === undefined) 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
         if (folder === '/') return undefined
@@ -31,16 +32,16 @@ export async function findProjectScope(pluginRoot: string, home: string, fs: Fil
 }
 
 async function readRepository(workTree: string, fs: FileSystem): Promise<string | undefined> {
-  const gitPath = resolvePath('.git', workTree)
+  const gitPath = resolve(workTree, '.git')
   const git = await fs.stat(gitPath).catch(() => undefined)
   if (git === undefined) return undefined
   if (git.kind === 'dir') return git.realPath ?? gitPath
   try {
     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),
+    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

package/src/jobs/permissions/match-target.ts

@@ -2,7 +2,8 @@ import { matchesGlob } from '../../utils/matches-glob.js'
 import { parseShell } from '../../utils/parse-shell.js'
 import { callBaseOf, type CallBase, type CallEffects, type CommandCall, type FetchCall, type FileAccess, type FileCall, type ToolCall, type ToolUse } from '../../utils/call-effects.js'
 import type { Workspace } from './find-project-scope.js'
-import { nameOf, realPathOf, relativePath } from '../../utils/paths.js'
+import { realPathOf, relativePath } from '../../utils/paths.js'
+import { basename } from '../../vendor.js'
 
 export type TargetCalls = { command: CommandCall; read: FileCall; write: FileCall; fetch: FetchCall; subagent: CallBase; tool: CallBase }
 export type TargetKey = keyof TargetCalls
@@ -56,11 +57,11 @@ export async function matchTarget(target: Target, use: ToolUse, effects: CallEff
 function commandPattern(pattern: string): [string, ...string[]] {
   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: [string, ...string[]], argv: [string, ...string[]]): boolean {
-  if (nameOf(argv[0]) !== nameOf(pattern[0])) return false
+  if (basename(argv[0]) !== basename(pattern[0])) return false
   const wanted = splitArguments(pattern.slice(1))
   const actual = splitArguments(argv.slice(1))
   let next = 0

package/src/mod.ts

@@ -1,11 +1,16 @@
 import type {
+  AgentSpawnArgs,
+  AgentSpawnResult,
   AskOptions,
   ClassicHookInputs,
   CmodDependencies,
   FsEntry,
+  FsStat,
+  FsStatOptions,
   HookStream,
   HttpInit,
   HttpResponse,
+  PaneOpenArgs,
   PermissionRequestDecision,
   ProcessRunInit,
   ProcessRunResult,
@@ -15,6 +20,8 @@ import type {
   RenderElement,
   Settings,
   SettingsReadArgs,
+  UiScrollArgs,
+  UiScrollResult,
 } from 'claude-code'
 import type { Claude } from './runtime/claude.js'
 import type { RoutedEvent } from './runtime/hooks.js'
@@ -30,9 +37,9 @@ export type ProgressStep = {
 }
 
 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
 }
 
@@ -59,6 +66,7 @@ export type ModEvent =
   | 'Stop'
   | 'StopFailure'
   | 'CwdChanged'
+  | 'FileChanged'
 
 export type HookAnswer = {
   continue?: boolean
@@ -104,7 +112,9 @@ 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
@@ -118,6 +128,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>
@@ -127,6 +138,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>
@@ -134,6 +147,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

package/src/path.ts

@@ -0,0 +1 @@
+export { basename, dirname, extname, isAbsolute, join, normalize, relative, resolve } from './vendor.js'

package/src/register.ts

@@ -21,6 +21,7 @@ async function startMod($: EngineInterface, eventInput: Frozen<Args<'session.sta
       open: (pane) => $.ui.open(pane),
       close: (pane) => $.ui.close(pane),
       panes: () => $.ui.panes(),
+      scroll: (args) => $.ui.scroll(args),
       resolve: (render) => $.ui.resolve(render),
     },
     process: {
@@ -54,10 +55,14 @@ async function startMod($: EngineInterface, eventInput: Frozen<Args<'session.sta
       model: () => $.session.model(),
       usage: () => $.session.usage(),
       surfaces: () => $.session.surfaces(),
+      messages: ((args?: Parameters<Claude['session']['messages']>[0]) => (args === undefined ? $.session.messages() : $.session.messages(args))) as Claude['session']['messages'],
     },
     command: { register: (command) => $.command.register(command) },
     tool: { register: (tool) => $.tool.register(tool) },
-    agent: { list: () => $.agent.list() },
+    agent: {
+      list: () => $.agent.list(),
+      spawn: (args) => $.agent.spawn(args),
+    },
     env: {
       home: () => $.env.get('HOME'),
       dataHome: () => $.env.get('XDG_DATA_HOME'),
@@ -91,6 +96,7 @@ export function registerMod<State extends object>(addHook: On, definition: ModDe
   addHook('classic.PreCompact', routeToMod)
   addHook('classic.Stop', routeToMod)
   addHook('classic.StopFailure', routeToMod)
+  addHook('classic.FileChanged', routeToMod)
   addHook('tool.call', routeToMod)
   addHook('prompt.submit', routeToMod)
   addHook('prompt.context', routeToMod)
@@ -99,6 +105,7 @@ export function registerMod<State extends object>(addHook: On, definition: ModDe
   addHook('skill.prompt', routeToMod)
   addHook('ui.render', routeToMod)
   addHook('ui.press', routeToMod)
+  addHook('ui.scroll', routeToMod)
   addHook('ui.close', routeToMod)
   addHook('cmod.call', routeToMod)
 }
@@ -106,6 +113,5 @@ export function registerMod<State extends object>(addHook: On, definition: ModDe
 export function registerPermissionCheck(addHook: On): void {
   checksPermissions = true
   addHook('tool.check', routeToMod)
-  addHook('classic.PreToolUse', routeToMod)
   addHook('classic.PermissionRequest', routeToMod)
 }

package/src/runtime/claude.ts

@@ -1,6 +1,9 @@
 import type {
   AgentInfo,
+  AgentSpawnArgs,
+  AgentSpawnResult,
   Args,
+  EngineInterface,
   AskOptions,
   CommandSpec,
   ElementTable,
@@ -29,6 +32,8 @@ import type {
   UiLogOptions,
   UiOpenResult,
   UiPane,
+  UiScrollArgs,
+  UiScrollResult,
 } from 'claude-code'
 
 export type Claude = {
@@ -43,6 +48,7 @@ export type Claude = {
     open(pane: PaneOpenArgs): Promise<UiOpenResult>
     close(pane: PaneCloseArgs): Promise<void>
     panes(): Promise<readonly UiPane[]>
+    scroll(args: UiScrollArgs): Promise<UiScrollResult>
     resolve(e: ResolveInput): ElementTable<RenderSurface>
   }
   readonly process: {
@@ -76,10 +82,14 @@ export type Claude = {
     model(): Promise<string>
     usage(): Promise<SessionUsage>
     surfaces(): Promise<readonly RenderSurface[]>
+    messages: EngineInterface['session']['messages']
   }
   readonly command: { register(command: CommandSpec): Promise<{ command: string }> }
   readonly tool: { register(tool: ToolSpec): Promise<{ tool: string }> }
-  readonly agent: { list(): Promise<AgentInfo[]> }
+  readonly agent: {
+    list(): Promise<AgentInfo[]>
+    spawn(args: AgentSpawnArgs): Promise<AgentSpawnResult>
+  }
   readonly env: {
     home(): Promise<string | undefined>
     dataHome(): Promise<string | undefined>

package/src/runtime/hooks.ts

@@ -1,15 +1,15 @@
-import type { Args, ClassicHookInputs, Frozen } from 'claude-code'
-import type { HookAnswer, ModEvent, ModHook } from '../mod.js'
+import type { Args, ClassicHookInputs, EventResult, Frozen } from 'claude-code'
+import type { HookAnswer, HookInput, ModEvent, ModHook } from '../mod.js'
 import { configFolders } from '../records.js'
 import type { Claude } from './claude.js'
 import type { RoutedHook } from './router.js'
-import { toolInputOf, type ToolCalls } from './tool-calls.js'
+import { reservedKeys, toolInputOf, type ToolCalls } from './tool-calls.js'
 import { callEffects, type FileAccess, type ToolUse } from '../utils/call-effects.js'
 import { dynamicPattern } from '../utils/parse-shell.js'
 import { messageOf } from '../utils/text.js'
 
 export type RoutedEvent =
-  | `classic.${ModEvent}`
+  | `classic.${Exclude<ModEvent, 'PreToolUse'>}`
   | 'tool.check'
   | 'tool.call'
   | 'prompt.submit'
@@ -19,16 +19,15 @@ export type RoutedEvent =
   | 'skill.prompt'
   | 'ui.render'
   | 'ui.press'
+  | 'ui.scroll'
   | 'ui.close'
   | 'cmod.call'
 
-export const permissionEvents: readonly RoutedEvent[] = ['tool.check', 'classic.PreToolUse', 'classic.PermissionRequest']
+export const permissionEvents: readonly RoutedEvent[] = ['tool.check', 'classic.PermissionRequest']
 
 type ClassicFields = Record<string, unknown>
 
-type PreToolUseInput = Parameters<ModHook<'PreToolUse'>>[0]
-
-type CallFiles = PreToolUseInput['files']
+type CallFiles = HookInput<'PreToolUse'>['files']
 
 const flags: readonly string[] = ['suppressOriginalPrompt', 'reloadSkills', 'retry']
 
@@ -50,18 +49,18 @@ const readFields: Record<ModEvent, readonly string[]> = {
   Stop: ['additionalContext'],
   StopFailure: [],
   CwdChanged: [],
+  FileChanged: [],
 }
 
-export function classicHook<E extends ModEvent>(name: string, event: E, hook: ModHook<E>, claude: Claude, calls: ToolCalls): RoutedHook<RoutedEvent> {
+export function classicHook<E extends Exclude<ModEvent, 'PreToolUse'>>(name: string, event: E, hook: ModHook<E>, claude: Claude, calls: ToolCalls): RoutedHook<RoutedEvent> {
   const inputOf = async (e: unknown): Promise<unknown> => {
-    if (event === 'PreToolUse') return preToolUseInput(name, e as Frozen<Args<'classic.PreToolUse'>>, claude, calls.agentOf)
     if (event !== 'PostToolUse' && event !== 'PostToolUseFailure') return e
     const input = e as ClassicHookInputs['PostToolUse' | 'PostToolUseFailure']
     const cwd = calls.cwdOf(input.tool_use_id) ?? input.cwd
     return { ...input, files: await callFiles(name, claude, { tool: input.tool_name, input: input.tool_input }, cwd) }
   }
   const resultOf = async (e: unknown): Promise<ClassicFields | undefined> => {
-    const answer = await hook((await inputOf(e)) as Parameters<ModHook<E>>[0])
+    const answer = await hook((await inputOf(e)) as HookInput<E>)
     if (answer === undefined) return undefined
     if (answer.systemMessage !== undefined) claude.ui.log(answer.systemMessage)
     return classicResult(event, answer)
@@ -69,17 +68,65 @@ export function classicHook<E extends ModEvent>(name: string, event: E, hook: Mo
   const routed = async (e: unknown, next: (e: unknown) => Promise<unknown>) => {
     const ours = await resultOf(e).catch((error: unknown): ClassicFields | undefined => {
       const reason = `${name}: the ${event} hook failed: ${messageOf(error)}`
-      if (event === 'PreToolUse') return { deny: reason }
       if (event === 'PermissionRequest') return { decision: { behavior: 'deny', message: reason } }
       claude.ui.log(reason)
       return undefined
     })
     if (ours === undefined) return next(e)
-    return mergeClassic(event, (await next(e)) as ClassicFields, ours)
+    return mergeClassic((await next(e)) as ClassicFields, ours)
   }
   return routed as unknown as RoutedHook<RoutedEvent>
 }
 
+type HeldDecision = { readonly decision: 'allow' | 'ask'; readonly reason?: string }
+
+export type HeldDecisions = Map<string, HeldDecision>
+
+export function preToolUseHook(name: string, hook: ModHook<'PreToolUse'>, claude: Claude, calls: ToolCalls, held: HeldDecisions | undefined): RoutedHook<'tool.call'> {
+  return async (e, next) => {
+    let ours: ClassicFields
+    try {
+      const answer = await hook(await preToolUseInput(name, e, claude, calls.agentOf))
+      if (answer?.systemMessage !== undefined) claude.ui.log(answer.systemMessage)
+      ours = answer === undefined ? {} : classicResult('PreToolUse', answer)
+    } catch (error) {
+      return { deny: `${name}: the PreToolUse hook failed: ${messageOf(error)}` }
+    }
+    if (typeof ours['deny'] === 'string') return { deny: ours['deny'] }
+    const decided = heldDecisionOf(ours)
+    if (decided !== undefined && held === undefined) {
+      return { deny: `${name}: the PreToolUse hook answered permissionDecision "${decided.decision}", so hooks/register.ts must call registerPermissionCheck(addHook) after registerMod.` }
+    }
+    const updated = ours['updatedInput'] as Record<string, unknown> | undefined
+    const reserved = Object.fromEntries(Object.entries(e).filter(([key]) => reservedKeys.includes(key)))
+    const earlier = held?.get(e.tool_use_id)
+    if (decided !== undefined) held?.set(e.tool_use_id, earlier !== undefined && strictness.indexOf(earlier.decision) >= strictness.indexOf(decided.decision) ? earlier : decided)
+    let result: EventResult<'tool.call'>
+    try {
+      result = await next(updated === undefined ? e : ({ ...reserved, ...updated } as Frozen<Args<'tool.call'>>))
+    } finally {
+      if (decided !== undefined) held?.delete(e.tool_use_id)
+    }
+    const context = ours['additionalContext'] as string[] | undefined
+    if (context === undefined || result.deny !== undefined) return result
+    return { ...result, context: [...(result.context ?? []), ...context] }
+  }
+}
+
+export function heldDecisionHook(held: HeldDecisions): RoutedHook<'tool.check'> {
+  return async (e, next) => {
+    const below = await next(e)
+    const ours = e.tool_use_id === undefined ? undefined : held.get(e.tool_use_id)
+    return ours === undefined || below.decision === 'deny' ? below : ours
+  }
+}
+
+function heldDecisionOf(ours: ClassicFields): HeldDecision | undefined {
+  if (ours['allow'] !== undefined) return { decision: 'allow' }
+  if (typeof ours['ask'] !== 'string') return undefined
+  return ours['ask'] === '' ? { decision: 'ask' } : { decision: 'ask', reason: ours['ask'] }
+}
+
 const frontmatter = /^---\r?\n[\s\S]*?\r?\n---[ \t]*(?:\r?\n|$)/
 
 const baseDirectoryLine = /^Base directory for this skill: [^\n]*\n\n/
@@ -101,7 +148,7 @@ export function userSkillHook(claude: Claude): RoutedHook<'skill.prompt'> {
   }
 }
 
-async function preToolUseInput(name: string, envelope: Frozen<Args<'classic.PreToolUse'>>, claude: Claude, agentOf: ToolCalls['agentOf']): Promise<PreToolUseInput> {
+async function preToolUseInput(name: string, envelope: Frozen<Args<'tool.call'>>, claude: Claude, agentOf: ToolCalls['agentOf']): Promise<HookInput<'PreToolUse'>> {
   const { tool, tool_use_id } = envelope
   const [session_id, cwd, { agentId, agentType }] = await Promise.all([claude.session.id(), claude.session.cwd(), agentOf(tool_use_id)])
   const tool_input = toolInputOf(envelope)
@@ -161,17 +208,9 @@ function classicResult(event: ModEvent, answer: HookAnswer): ClassicFields {
 
 export const strictness = ['allow', 'ask', 'deny'] as const
 
-function strictnessOf(result: ClassicFields): number {
-  return strictness.findLastIndex((decision) => result[decision] !== undefined)
-}
-
-function mergeClassic(event: ModEvent, below: ClassicFields, ours: ClassicFields): ClassicFields {
+function mergeClassic(below: ClassicFields, ours: ClassicFields): ClassicFields {
   const merged: ClassicFields = { ...below, ...ours }
   const context = [...((below['additionalContext'] as string[] | undefined) ?? []), ...((ours['additionalContext'] as string[] | undefined) ?? [])]
   if (context.length > 0) merged['additionalContext'] = context
-  if (event !== 'PreToolUse') return merged
-  const strictest = strictness[Math.max(strictnessOf(below), strictnessOf(ours))]
-  for (const decision of strictness) delete merged[decision]
-  if (strictest !== undefined) merged[strictest] = ours[strictest] ?? below[strictest]
   return merged
 }

package/src/runtime/lifecycle.ts

@@ -1,12 +1,12 @@
 import type { Args, EventResult, Frozen, HookBudget, HookStream, ProcessSpawnChunk, ProcessSpawnResult } from 'claude-code'
-import type { Mod, ModDefinition, ModEvent, ModHook } from '../mod.js'
+import type { HookInput, Mod, ModDefinition, ModEvent, ModHook } from '../mod.js'
 import { dataFolder, isAtLeast, parseEvent, readRecord, readSteps, scriptsSha256, storeFolder, type ReadFile, type RunnerEvent } from '../records.js'
 import { relativePath } from '../utils/paths.js'
 import { formatExit, listed, messageOf } from '../utils/text.js'
 import type { Claude } from './claude.js'
 import { beforeDeadline } from './deadline.js'
 import { answerCall, dependencyCalls, notInstalled } from './dependencies.js'
-import { classicHook, permissionEvents, userSkillHook, type RoutedEvent } from './hooks.js'
+import { classicHook, heldDecisionHook, permissionEvents, preToolUseHook, userSkillHook, type HeldDecisions, type RoutedEvent } from './hooks.js'
 import { createRouter, type Router, type RouterNext } from './router.js'
 import { createState } from './state.js'
 import { toolCalls } from './tool-calls.js'
@@ -362,13 +362,15 @@ async function createMod<State extends object>(definition: ModDefinition<State>,
   let staleCwd: string | undefined
   const area = createUi<State>({ name: definition.name, claude, router, progress, announce, mod: () => mod })
   const modState = createState<State>({ name: definition.name, initial: definition.state ?? {}, session, root, claude, changed: area.changed })
+  const held: HeldDecisions | undefined = runtime.checksPermissions() ? new Map() : undefined
   const mod: Mod<State> = {
     name: definition.name,
     state: modState.state,
     dataFolder: runtime.dataFolder,
     on(event, hook) {
       if (!hookEvents.includes(event)) hookEvents.push(event)
-      router.add(`classic.${event}`, classicHook(definition.name, event, hook, claude, agents))
+      if (event === 'PreToolUse') router.add('tool.call', preToolUseHook(definition.name, hook as ModHook<'PreToolUse'>, claude, agents, held))
+      else router.add(`classic.${event as Exclude<ModEvent, 'PreToolUse'>}`, classicHook(definition.name, event as Exclude<ModEvent, 'PreToolUse'>, hook as ModHook<Exclude<ModEvent, 'PreToolUse'>>, claude, agents))
     },
     use: (job) => job({ mod, claude, on: (event, hook) => router.add(event, hook), announce, reserveName, toolCalls: agents }),
     ui: area.ui,
@@ -380,9 +382,13 @@ async function createMod<State extends object>(definition: ModDefinition<State>,
       read: (path) => claude.fs.read(path),
       write: (path, text) => claude.fs.write(path, text),
       list: (path) => claude.fs.list(path),
+      exists: (path) => claude.fs.exists(path),
+      stat: (path, options) => claude.fs.stat(path, options),
     },
     http: { fetch: (url, init) => claude.http.fetch(url, init) },
     settings: { read: (args) => claude.settings.read(args) },
+    session: { messages: claude.session.messages },
+    agent: { spawn: (args) => claude.agent.spawn(args) },
     get projectRoot() {
       return modState.root
     },
@@ -408,7 +414,7 @@ async function createMod<State extends object>(definition: ModDefinition<State>,
       loadedCwd = nextCwd
       if (!hasMovedRoot) area.changed()
       if (nextCwd === oldCwd) return
-      const moved: Parameters<ModHook<'CwdChanged'>>[0] = { session_id: await claude.session.id(), cwd: nextCwd, hook_event_name: 'CwdChanged', old_cwd: oldCwd, new_cwd: nextCwd }
+      const moved: HookInput<'CwdChanged'> = { session_id: await claude.session.id(), cwd: nextCwd, hook_event_name: 'CwdChanged', old_cwd: oldCwd, new_cwd: nextCwd }
       await router.dispatch('classic.CwdChanged', moved as Frozen<Args<'classic.CwdChanged'>>, async () => ({}))
     } catch (error) {
       claude.ui.log(`${definition.name} keeps the state of ${modState.root} until the next prompt or folder move: ${messageOf(error)}`)
@@ -452,6 +458,7 @@ async function createMod<State extends object>(definition: ModDefinition<State>,
   if (permissionHooks.length > 0 && !runtime.checksPermissions()) {
     throw new Error(`it decides permissions on ${listed(permissionHooks)}, so hooks/register.ts must call registerPermissionCheck(addHook) after registerMod`)
   }
+  if (held !== undefined && hookEvents.includes('PreToolUse')) router.add('tool.check', heldDecisionHook(held))
   await failsAs('its open panes did not load', () => area.restorePanes())
   if (hookEvents.length > 0) added.push(`${hookEvents.length === 1 ? 'a hook' : 'hooks'} on ${listed(hookEvents)}`)
   return { mod, added }

package/src/runtime/ui.ts

@@ -224,6 +224,7 @@ export type UiArea<State extends object> = {
 
 export function createUi<State extends object>({ name, claude, router, progress, announce, mod }: UiOptions<State>): UiArea<State> {
   const panes = new Map<string, Pane<State>>()
+  const paneLogs = new Map<string, (failure: string) => void>()
   const openPanes = new Set<string>()
   const requestedSizes = new Map<string, PaneSize>()
   const renders = new Set<string>()
@@ -291,9 +292,10 @@ export function createUi<State extends object>({ name, claude, router, progress,
     })
   }
 
-  const openAt = (pane: Pane<State>, size: PaneSize) => {
+  const openAt = (pane: Pane<State>, size: PaneSize, focus?: true) => {
     requestedSizes.set(pane.id, size)
-    return claude.ui.open({ id: pane.id, title: pane.title, ...size })
+    const { id, title, closeOnEscape, holdToasts } = pane
+    return claude.ui.open({ id, title, ...size, ...(closeOnEscape === true ? { closeOnEscape } : {}), ...(holdToasts === true ? { holdToasts } : {}), ...(focus === true ? { focus } : {}) })
   }
 
   const resize = async (pane: Pane<State>) => {
@@ -315,34 +317,58 @@ export function createUi<State extends object>({ name, claude, router, progress,
       if (pane === undefined || e.component !== 'Pane') return next(e)
       openPanes.add(pane.id)
       const table = claude.ui.resolve(e)
-      return drawWith(table, () => pane.render(mod(), e.props), markdownIn(table))
+      try {
+        return drawWith(table, () => pane.render(mod(), e.props), markdownIn(table))
+      } catch (error) {
+        paneLogs.get(pane.id)?.(`threw: ${messageOf(error)}`)
+        return drawWith(table, () => Text({ color: 'error', children: `The ${pane.title} pane could not draw: ${messageOf(error)}` }))
+      }
+    })
+    router.add('ui.scroll', async (e, next) => {
+      const pane = panes.get(e.requestId)
+      const moved = await next(e)
+      if (pane?.onScroll === undefined || e.component !== 'Pane' || moved.deny !== undefined) return moved
+      await handle(pane, 'onScroll', () => pane.onScroll?.(mod(), e))
+      return moved
     })
-    router.add('ui.close', (e, next) => {
+    router.add('ui.close', async (e, next) => {
       openPanes.delete(e.id)
-      return next(e)
+      const closed = await next(e)
+      const pane = panes.get(e.id)
+      if (pane?.onClose !== undefined) await handle(pane, 'onClose', () => pane.onClose?.(mod(), e))
+      return closed
     })
   }
 
+  const handle = async (pane: Pane<State>, handler: string, run: () => unknown) => {
+    try {
+      await run()
+    } catch (error) {
+      claude.ui.log(`${name}: the ${pane.title} pane's ${handler} threw: ${messageOf(error)}`)
+    }
+  }
+
   return {
     ui: {
       pane(pane) {
         if (panes.has(pane.id)) throw new Error(`${name}: the pane "${pane.id}" is already added. Give each pane its own id.`)
         panes.set(pane.id, pane)
+        paneLogs.set(pane.id, logOnce(`${pane.title} pane`))
         announce(`the ${pane.title} pane`)
         route()
         const handle: PaneHandle = {
           get isOpen() {
             return openPanes.has(pane.id)
           },
-          async open() {
-            const { isPlaced } = await openAt(pane, paneSize(pane, mod().state))
+          async open(options) {
+            const { isPlaced } = await openAt(pane, paneSize(pane, mod().state), options?.focus)
             if (isPlaced) openPanes.add(pane.id)
           },
           async close() {
             await claude.ui.close({ id: pane.id })
             openPanes.delete(pane.id)
           },
-          toggle: () => (openPanes.has(pane.id) ? handle.close() : handle.open()),
+          toggle: (options) => (openPanes.has(pane.id) ? handle.close() : handle.open(options)),
         }
         return handle
       },
@@ -386,6 +412,7 @@ export function createUi<State extends object>({ name, claude, router, progress,
         }
       },
       ask: (question, options) => claude.ui.ask(question, options),
+      scroll: (args) => claude.ui.scroll(args),
     },
     changed() {
       if (panes.size === 0 && renders.size === 0) return

package/src/shell.ts

@@ -0,0 +1 @@
+export { parseShell, type ParsedShell, type ShellCommand } from './utils/parse-shell.js'

package/src/testing/fake-claude.ts

@@ -12,8 +12,9 @@ export type Fakes = {
   fs: { read?: Claude['fs']['read']; write?: Claude['fs']['write']; list?: Claude['fs']['list']; exists?: Claude['fs']['exists']; stat?: Claude['fs']['stat'] }
   http: { fetch?: Claude['http']['fetch'] }
   settings: { read?: Claude['settings']['read'] }
-  ui: { ask?: Claude['ui']['ask']; open?: Claude['ui']['open'] }
-  agent: { list?: Claude['agent']['list'] }
+  ui: { ask?: Claude['ui']['ask']; open?: Claude['ui']['open']; scroll?: Claude['ui']['scroll'] }
+  session: { messages?: Claude['session']['messages'] }
+  agent: { list?: Claude['agent']['list']; spawn?: Claude['agent']['spawn'] }
   clock: { after?: Claude['clock']['after']; every?: Claude['clock']['every'] }
   cmod: { call?: Claude['cmod']['call'] }
 }
@@ -39,9 +40,10 @@ export type FakeClaude = {
 
 export function fakeClaude(plugin: { readonly name: string; readonly root: string }): FakeClaude {
   const calls: TestCall[] = []
-  const fakes: Fakes = { process: {}, fs: {}, http: {}, settings: {}, ui: {}, agent: {}, clock: {}, cmod: {} }
+  const fakes: Fakes = { process: {}, fs: {}, http: {}, settings: {}, ui: {}, session: {}, agent: {}, clock: {}, cmod: {} }
   const shown: Shown = { toasts: [], logs: [], debug: [], statuses: [], openPanes: new Set(), commands: [], tools: [] }
   const unplacedPanes = new Set<string>()
+  let focusedPane: string | undefined
   const store = new Map<string, unknown>()
 
   const faked = <Args extends readonly unknown[], Result>(call: string, answer: () => ((...args: Args) => Result) | undefined) => {
@@ -81,6 +83,7 @@ export function fakeClaude(plugin: { readonly name: string; readonly root: strin
         if (answer.isPlaced) {
           shown.openPanes.add(pane.id)
           unplacedPanes.delete(pane.id)
+          if (pane.focus === true) focusedPane = pane.id
         } else if (!shown.openPanes.has(pane.id)) {
           unplacedPanes.add(pane.id)
         }
@@ -90,11 +93,13 @@ export function fakeClaude(plugin: { readonly name: string; readonly root: strin
         calls.push({ call: 'ui.close', args: [pane] })
         shown.openPanes.delete(pane.id)
         unplacedPanes.delete(pane.id)
+        if (focusedPane === pane.id) focusedPane = undefined
       },
       panes: async () => [
-        ...[...shown.openPanes].map((id) => ({ id, title: id, isShown: true, isFocused: false, isPlaced: true })),
+        ...[...shown.openPanes].map((id) => ({ id, title: id, isShown: true, isFocused: id === focusedPane, isPlaced: true })),
         ...[...unplacedPanes].map((id) => ({ id, title: id, isShown: false, isFocused: false, isPlaced: false })),
       ],
+      scroll: rejected('ui.scroll', () => fakes.ui.scroll ?? (async () => ({}))),
       resolve: () => elements,
     },
     process: {
@@ -110,7 +115,10 @@ export function fakeClaude(plugin: { readonly name: string; readonly root: strin
     },
     http: { fetch: rejected('http.fetch', () => fakes.http.fetch) },
     settings: { read: rejected('settings.read', () => fakes.settings.read) },
-    agent: { list: rejected('agent.list', () => fakes.agent.list) },
+    agent: {
+      list: rejected('agent.list', () => fakes.agent.list),
+      spawn: rejected('agent.spawn', () => fakes.agent.spawn),
+    },
     store: {
       get: async (key) => store.get(key),
       set: async (key, value) => {
@@ -133,6 +141,7 @@ export function fakeClaude(plugin: { readonly name: string; readonly root: strin
       model: async () => 'test-model',
       usage: async () => ({ context: { window: 200000 }, rateLimits: {}, cost: { usd: 0 } }) as unknown as Awaited<ReturnType<Claude['session']['usage']>>,
       surfaces: async () => ['terminal'],
+      messages: rejected('session.messages', () => fakes.session.messages as ((args?: unknown) => Promise<unknown>) | undefined) as Claude['session']['messages'],
     },
     command: {
       register: async (command) => {