@cmodjs/core 2.0.1 → 3.0.0

package/src/runtime/permission-check.ts

@@ -4,6 +4,7 @@ import { defined, processPayloadOf, recordOf, type HookOn, type RouteOn, type To
 
 export type PermissionUse = {
   readonly raise: (method: string, payload: HookFields) => Promise<HookFields | undefined>
+  readonly refusalFor: (method: string, payload: HookFields, error: Error) => { readonly refuse: string } | undefined
   readonly hookOn: HookOn
   readonly routeOn: RouteOn
   readonly current: () => { readonly id: string; readonly cwd: string }
@@ -15,33 +16,54 @@ type Verdict = { readonly decision: 'allow' | 'ask' | 'deny'; readonly reason?:
 
 const verdictName = (decision: Verdict['decision']) => (decision === 'deny' ? 'refuse' : decision)
 
-export const permissionRoutes: PermissionRoutes = (method, { raise, hookOn, routeOn, current }) => {
+export const permissionRoutes: PermissionRoutes = (method, { raise, refusalFor, hookOn, routeOn, current }) => {
   const isBefore = method.startsWith('before')
   if (method.endsWith('PermissionCheck')) {
-    return routeOn('tool.check', async (e: ToolCheck, next) => {
-      const below = (await next(e)) as Verdict
+    const payloadOf = (e: ToolCheck, below: Verdict) => {
       const { id, cwd } = current()
-      const payload = { session: id, cwd, ...defined({ task: e.agentId, callId: e.tool_use_id, reason: below.reason, rule: below.rule, ceiling: e.ceiling === undefined ? undefined : verdictName(e.ceiling) }), name: e.tool, input: recordOf(e.input), decision: verdictName(below.decision) }
+      return { session: id, cwd, ...defined({ task: e.agentId, callId: e.tool_use_id, reason: below.reason, rule: below.rule, ceiling: e.ceiling === undefined ? undefined : verdictName(e.ceiling) }), name: e.tool, input: recordOf(e.input), decision: verdictName(below.decision) }
+    }
+    const failed = async (e: ToolCheck, error: Error, next: (e: ToolCheck) => Promise<unknown>) => {
+      const refusal = refusalFor(method, payloadOf(e, (await next(e)) as Verdict), error)
+      return refusal === undefined ? undefined : { decision: 'deny' as const, reason: refusal.refuse }
+    }
+    return routeOn(
+      'tool.check',
+      async (e: ToolCheck, next) => {
+        const below = (await next(e)) as Verdict
+        const payload = payloadOf(e, below)
+        if (!isBefore) {
+          void raise(method, payload)
+          return below
+        }
+        const answer = await raise(method, payload)
+        if (answer === undefined || below.decision === 'deny') return below
+        if (typeof answer['refuse'] === 'string') return { decision: 'deny', reason: answer['refuse'] }
+        if (typeof answer['ask'] === 'string') return { decision: 'ask', reason: answer['ask'] }
+        return answer['allow'] === true ? { decision: 'allow' } : below
+      },
+      isBefore ? failed : undefined,
+    )
+  }
+  const refused = (refuse: string, interrupt?: unknown) => ({ decision: defined({ behavior: 'deny', message: refuse, interrupt }) })
+  return hookOn(
+    'PermissionRequest',
+    async (input) => {
+      const payload = processPayloadOf('PermissionRequest', input)
       if (!isBefore) {
         void raise(method, payload)
-        return below
+        return undefined
       }
       const answer = await raise(method, payload)
-      if (answer === undefined || below.decision === 'deny') return below
-      if (typeof answer['refuse'] === 'string') return { decision: 'deny', reason: answer['refuse'] }
-      if (typeof answer['ask'] === 'string') return { decision: 'ask', reason: answer['ask'] }
-      return answer['allow'] === true ? { decision: 'allow' } : below
-    })
-  }
-  return hookOn('PermissionRequest', async (input) => {
-    const payload = processPayloadOf('PermissionRequest', input)
-    if (!isBefore) {
-      void raise(method, payload)
-      return undefined
-    }
-    const answer = await raise(method, payload)
-    if (answer === undefined) return undefined
-    if (typeof answer['refuse'] === 'string') return { decision: defined({ behavior: 'deny', message: answer['refuse'], interrupt: answer['interrupt'] }) }
-    return answer['allow'] === true ? { decision: defined({ behavior: 'allow', updatedInput: answer['input'], updatedPermissions: answer['updates'] }) } : undefined
-  })
+      if (answer === undefined) return undefined
+      if (typeof answer['refuse'] === 'string') return refused(answer['refuse'], answer['interrupt'])
+      return answer['allow'] === true ? { decision: defined({ behavior: 'allow', updatedInput: answer['input'], updatedPermissions: answer['updates'] }) } : undefined
+    },
+    isBefore
+      ? (input, error) => {
+          const refusal = refusalFor(method, processPayloadOf('PermissionRequest', input), error)
+          return refusal === undefined ? undefined : refused(refusal.refuse)
+        }
+      : undefined,
+  )
 }

package/src/runtime/router.ts

@@ -6,38 +6,46 @@ export type RouterNext<N extends RoutedEvent> = (e: Frozen<Args<N>>) => Promise<
 
 export type RoutedHook<N extends RoutedEvent> = (e: Frozen<Args<N>>, next: RouterNext<N>) => EventResult<N> | Promise<EventResult<N>>
 
+export type RoutedFailure<N extends RoutedEvent> = (e: Frozen<Args<N>>, error: Error, next: RouterNext<N>) => EventResult<N> | undefined | Promise<EventResult<N> | undefined>
+
 export type Router = {
-  add<N extends RoutedEvent>(event: N, hook: RoutedHook<N>): Disposable
-  has(event: RoutedEvent): boolean
+  add<N extends RoutedEvent>(event: N, hook: RoutedHook<N>, failed?: RoutedFailure<N>): Disposable
   dispatch<N extends RoutedEvent>(event: N, e: Frozen<Args<N>>, next: RouterNext<N>): Promise<EventResult<N>>
+  dispatchFailure<N extends RoutedEvent>(event: N, e: Frozen<Args<N>>, error: Error, next: RouterNext<N>): Promise<EventResult<N>>
 }
 
-type ErasedHook = (e: unknown, next: (e: unknown) => Promise<unknown>) => unknown
+type Route = { readonly hook: (e: unknown, next: (e: unknown) => Promise<unknown>) => unknown; readonly failed?: (e: unknown, error: Error, next: (e: unknown) => Promise<unknown>) => unknown }
 
 export function createRouter(): Router {
-  const hooks = new Map<RoutedEvent, ErasedHook[]>()
+  const routes = new Map<RoutedEvent, Route[]>()
 
   return {
-    add(event, hook) {
-      const erased = hook as unknown as ErasedHook
-      hooks.set(event, [...(hooks.get(event) ?? []), erased])
+    add(event, hook, failed) {
+      const route = { hook, ...(failed === undefined ? {} : { failed }) } as Route
+      routes.set(event, [...(routes.get(event) ?? []), route])
       return {
         dispose() {
-          const chain = (hooks.get(event) ?? []).filter((each) => each !== erased)
-          if (chain.length === 0) hooks.delete(event)
-          else hooks.set(event, chain)
+          const chain = (routes.get(event) ?? []).filter((each) => each !== route)
+          if (chain.length === 0) routes.delete(event)
+          else routes.set(event, chain)
         },
       }
     },
-    has: (event) => hooks.has(event),
     dispatch<N extends RoutedEvent>(event: N, e: Frozen<Args<N>>, next: RouterNext<N>): Promise<EventResult<N>> {
-      const chain = hooks.get(event)
+      const chain = routes.get(event)
       const call = async (index: number, current: unknown): Promise<unknown> => {
-        const hook = chain?.[index]
-        if (hook === undefined) return next(current as Frozen<Args<N>>)
-        return hook(current, (passed) => call(index + 1, passed))
+        const route = chain?.[index]
+        if (route === undefined) return next(current as Frozen<Args<N>>)
+        return route.hook(current, (passed) => call(index + 1, passed))
       }
       return call(0, e) as Promise<EventResult<N>>
     },
+    async dispatchFailure<N extends RoutedEvent>(event: N, e: Frozen<Args<N>>, error: Error, next: RouterNext<N>): Promise<EventResult<N>> {
+      for (const route of routes.get(event) ?? []) {
+        const answer = await route.failed?.(e, error, next as (e: unknown) => Promise<unknown>)
+        if (answer !== undefined) return answer as EventResult<N>
+      }
+      return next(e)
+    },
   }
 }

package/src/runtime/sessions.ts

@@ -1,8 +1,8 @@
-import type { Args, CommandRunResult } from 'claude-code'
+import type { Args, CommandRunResult, SessionCompactResult } from 'claude-code'
 import type { Disposable } from '../mod.js'
 import { ContextEnd, ContextStart, type Context } from '../session/context/context.js'
 import { Message, noFiles } from '../session/context/turn/message/message.js'
-import { Note } from '../session/context/turn/message/note.js'
+import { modNote, Note } from '../session/context/turn/message/note.js'
 import { Person, senderOf } from '../session/context/turn/message/sender.js'
 import { ToolCall } from '../session/context/turn/message/tool-call.js'
 import { ToolResult } from '../session/context/turn/message/tool-result.js'
@@ -20,7 +20,7 @@ import { listenerOf, PassedTimeout, withinTime, type ListenOptions, type ListenT
 import { callFiles, type HomeFolders, type HookFields } from './hooks.js'
 import type { PermissionRoutes } from './permission-check.js'
 
-export type Subscription = { readonly event: SessionEvent; readonly matcher: SentMatcher | undefined }
+export type Subscription = { readonly event: SessionEvent; readonly matcher: SentMatcher | undefined; readonly onFailure?: 'refuse'; readonly scope?: Scope }
 
 export const everySession = '*'
 
@@ -67,6 +67,7 @@ export type SessionsClient = {
   readonly sessions: Sessions
   changed(session: string, change: SessionChange, isInProject: boolean): void
   answerBefore(session: string, event: BeforeEvent, change: SessionChange, isInProject: boolean): Promise<unknown>
+  failedBefore(session: string, event: BeforeEvent, change: SessionChange, isInProject: boolean, error: Error): { readonly refuse: string } | undefined
   raise(method: string, payload: Readonly<Record<string, unknown>>): Promise<unknown>
   listen(method: string, args: readonly unknown[]): Disposable
   /** An empty title keeps the title the session already has. */
@@ -133,7 +134,11 @@ export function isInScope(scope: Scope, session: string, change: SessionChange,
   return (change.type === TurnStart || change.type === TurnEnd) && change.turn.prompt.id === scope.turn
 }
 
-export type HookOn = (hook: string, listener: (input: unknown) => HookFields | undefined | Promise<HookFields | undefined>) => Disposable
+export function withoutPermissionCheck(name: string, hearer: string): string {
+  return `${name}: ${hearer} hears Claude Code's permission check, so hooks/register.ts must call registerPermissionCheck(addHook) after registerMod.`
+}
+
+export type HookOn = (hook: string, listener: (input: unknown) => HookFields | undefined | Promise<HookFields | undefined>, failed?: (input: unknown, error: Error) => HookFields | undefined) => Disposable
 
 export function createSessionsClient({ name, claude, report, isGranted, hookOn, routeOn, permissionRoutes }: { readonly name: string; readonly claude: Claude; readonly report: (id: string, message: string, error: unknown) => void; readonly isGranted: (permission: string) => boolean; readonly hookOn?: HookOn; readonly routeOn?: RouteOn; readonly permissionRoutes?: () => PermissionRoutes | undefined }): SessionsClient {
   const call = <Answer>(method: string, input: unknown) => claude.cmod.call({ to: cmodPluginName, method, input }) as Promise<Answer>
@@ -151,7 +156,8 @@ export function createSessionsClient({ name, claude, report, isGranted, hookOn,
     queued.add(key)
     void Promise.resolve().then(async () => {
       queued.delete(key)
-      const heard = (from: Map<string, Set<Listening>>): Subscription[] => [...(from.get(key) ?? [])].map(({ event, matcher }) => ({ event, matcher: matcher === undefined ? undefined : sentMatcher(matcher) }))
+      const heard = (from: Map<string, Set<Listening>>): Subscription[] =>
+        [...(from.get(key) ?? [])].map(({ event, matcher, options, scope }) => ({ event, matcher: matcher === undefined ? undefined : sentMatcher(matcher), ...(options.onFailure === 'refuse' ? { onFailure: 'refuse' as const, scope } : {}) }))
       const tracksTasks = [...(listening.get(key) ?? []), ...(deciding.get(key) ?? [])].some(({ scope }) => scope.task !== undefined || scope.isGoal === true)
       const subscriptions = [...heard(listening), ...(tracksTasks ? [{ event: TaskStart }] : [])]
       await call(conversationMethods.subscribe, { session: key, subscriptions }).catch((error: unknown) => report(`sessions:${key}`, `Hears nothing from ${key === everySession ? 'the other sessions' : `session ${key}`}`, error))
@@ -196,27 +202,32 @@ export function createSessionsClient({ name, claude, report, isGranted, hookOn,
     }
   }
 
-
+  const refusalOf = (options: ListenOptions, takes: readonly string[], error: unknown) => (options.onFailure === 'refuse' && takes.includes('refuse') ? { refuse: `${name}: ${messageOf(error)}` } : undefined)
 
   const invoke = (method: string, options: ListenOptions, run: (time: ListenTime) => unknown, takes: readonly string[] = []): Promise<unknown> =>
     withinTime(claude.clock, method, options, run).catch((error: unknown) => {
       if (error instanceof PassedTimeout && !method.startsWith('before')) return undefined
       report(`session:${method}`, `The ${method} listener failed`, error)
-      return options.onFailure === 'refuse' && takes.includes('refuse') ? { refuse: `${name}: ${messageOf(error)}` } : undefined
+      return refusalOf(options, takes, error)
     })
 
+  const decidersOf = (session: string, event: BeforeEvent, isInProject: boolean) => [...(deciding.get(session) ?? []), ...(isInProject ? (deciding.get(everySession) ?? []) : [])].filter((entry) => entry.event === event)
+
+  const decides = (entry: Listening, session: string, change: SessionChange) => isInScope(entry.scope, session, change, isUnderIn(session)) && (entry.matcher === undefined || matches(payloadOf(change), entry.matcher))
+
+  const mayDecide = (session: string) => session === current.id || isGranted('conversation')
+
   const combined = async (session: string, event: BeforeEvent, change: SessionChange, isInProject: boolean): Promise<Partial<Answers> | undefined> => {
-    const askers = [...(deciding.get(session) ?? []), ...(isInProject ? (deciding.get(everySession) ?? []) : [])]
-      .filter((entry) => entry.event === event)
+    const askers = decidersOf(session, event, isInProject)
       .map((entry) => async (latest: SessionChange) => {
-        if (!isInScope(entry.scope, session, latest, isUnderIn(session))) return undefined
-        if (entry.matcher !== undefined && !matches(payloadOf(latest), entry.matcher)) return undefined
+        if (!decides(entry, session, latest)) return undefined
         const payload = await payloadFor(session, latest)
         const answer = await invoke(entry.method, entry.options, async (time) => takenAnswer(entry.method, beforeAnswerKeys[event], await entry.listener(payload as never, time)), beforeAnswerKeys[event])
         if (answer === undefined || answer === null || (typeof answer === 'object' && 'refuse' in answer) || isGranted(beforePermission(event))) return answer
         throw new Error(`Its ${entry.method} answer changes nothing until ${beforePermission(event)} is turned on for ${name} in /mods.`)
       })
-    return foldBefore(event, change, askers, (error) => report(`session:${methodOf('before', event)}`, `The ${methodOf('before', event)} listener failed`, error))
+    const answer = await foldBefore(event, change, askers, (error) => report(`session:${methodOf('before', event)}`, `The ${methodOf('before', event)} listener failed`, error))
+    return answer?.note === undefined ? answer : { ...answer, note: modNote(name, answer.note) }
   }
 
   const eventMethods = (scopeOf: () => Scope, hasBefore: boolean, ended?: string): OnMethods & Partial<BeforeMethods> => {
@@ -325,7 +336,7 @@ export function createSessionsClient({ name, claude, report, isGranted, hookOn,
   const sendHere = async ({ type, text, as }: SessionSend) => {
     if (type === Note) {
       if (as !== undefined) throw new Error(`${name}: a Note is always from this mod, so it takes no as.`)
-      const added = await claude.session.append({ message: { type: 'user', content: [{ type: 'text', text }] } })
+      const added = await claude.session.append({ message: { type: 'user', content: [{ type: 'text', text: modNote(name, text) }] } })
       if (added.deny !== undefined) throw new Error(`${name}: Claude Code refused the note: ${added.deny}`)
       return
     }
@@ -428,21 +439,26 @@ export function createSessionsClient({ name, claude, report, isGranted, hookOn,
     )
   }
 
-  type ProcessListener = { readonly matcher: unknown; readonly listener: (payload: HookFields, time: ListenTime) => unknown; readonly options: ListenOptions }
+  type ProcessListener = { readonly matcher: unknown; readonly listener: (payload: HookFields, time: ListenTime) => unknown; readonly options: ListenOptions; readonly isEveryAgent: boolean }
   const processListeners = new Map<string, Set<ProcessListener>>()
 
+  const processHearers = (method: string, payload: HookFields) => [...(processListeners.get(method) ?? [])].filter(({ matcher, isEveryAgent }) => (payload['task'] === undefined || isEveryAgent) && (matcher === undefined || matches(payload, matcher)))
+
   const raise = async (method: string, payload: HookFields): Promise<HookFields | undefined> => {
-    const heard = [...(processListeners.get(method) ?? [])].filter(({ matcher }) => payload['task'] === undefined && (matcher === undefined || matches(payload, matcher)))
+    const heard = processHearers(method, payload)
     if (!method.startsWith('before')) {
       await Promise.all(heard.map(({ listener, options }) => invoke(method, options, (time) => listener(payload, time))))
       return undefined
     }
-    const failing = method === 'beforePermissionRequest' ? { onFailure: 'refuse' as const } : {}
-    const takes = answerKeys[method.slice('before'.length)] ?? []
-    const askers = heard.map(({ listener, options }) => () => invoke(method, { ...options, ...failing }, async (time) => takenAnswer(method, takes, await listener(payload, time)), takes))
+    const takes = takesOf(method)
+    const askers = heard.map(({ listener, options }) => () => invoke(method, options, async (time) => takenAnswer(method, takes, await listener(payload, time)), takes))
     return foldAnswers<undefined, HookFields>(method, takes, ['refuse'], undefined, askers, (error) => report(`session:${method}`, `The ${method} listener failed`, error))
   }
 
+  const takesOf = (method: string) => answerKeys[method.slice('before'.length)] ?? []
+
+  const refusalFor = (method: string, payload: HookFields, error: Error) => processHearers(method, payload).map((entry) => refusalOf(entry.options, takesOf(method), error)).find((answer) => answer !== undefined)
+
   const commandRun = async (e: Args<'command.run'>): Promise<HookFields> => {
     const source = (await claude.command.list()).find((command) => command.name === e.command)?.source
     return { session: current.id, cwd: current.cwd, name: e.command, args: e.args, ...defined({ source }), from: senderOf(e.origin, false) }
@@ -461,7 +477,10 @@ export function createSessionsClient({ name, claude, report, isGranted, hookOn,
     const args = typeof changes?.['args'] === 'string' ? changes['args'] : e.args
     const ran = await next(args === e.args ? e : { ...e, args })
     void raise('onRun', { ...run, args })
-    return typeof changes?.['note'] === 'string' ? { ...ran, context: [...(ran.context ?? []), changes['note']] } : ran
+    return typeof changes?.['note'] === 'string' ? { ...ran, context: [...(ran.context ?? []), modNote(name, changes['note'])] } : ran
+  }, async (e, error) => {
+    const refusal = commandListeners.beforeRun.size === 0 ? undefined : refusalFor('beforeRun', await commandRun(e), error)
+    return refusal === undefined ? undefined : { text: refusal.refuse }
   })
 
   const listenTo = (method: string, named: string) => {
@@ -469,24 +488,55 @@ export function createSessionsClient({ name, claude, report, isGranted, hookOn,
     const isBefore = method.startsWith('before')
     if (named === 'PermissionCheck' || named === 'PermissionRequest') {
       const routes = permissionRoutes?.()
-      if (routes !== undefined) return routes(method, { raise, hookOn, routeOn, current: () => current })
-      return named === 'PermissionCheck' ? routeOn('tool.check', (e, next) => next(e)) : hookOn('PermissionRequest', () => undefined)
+      if (routes === undefined) throw new Error(withoutPermissionCheck(name, method))
+      return routes(method, { raise, refusalFor, hookOn, routeOn, current: () => current })
     }
     const event: { readonly on: string; readonly before?: string } = processEvents[named as ProcessName]
     const hook = (isBefore ? event.before : undefined) ?? event.on
-    return hookOn(hook, async (input: unknown) => {
-      const payload = processPayloadOf(named as ProcessFieldsName, input)
-      if (!isBefore) {
-        if (named !== 'SessionStart' || payload['source'] !== 'compact') void raise(method, payload)
-        return undefined
-      }
-      const answer = await raise(method, payload)
-      return answer === undefined ? undefined : hookAnswerOf(named, answer)
-    })
+    if (method === 'beforeSessionStart') routeOn('session.compact', compactionNote)
+    const failed = (input: unknown, error: Error) => {
+      const refusal = refusalFor(method, processPayloadOf(named as ProcessFieldsName, input), error)
+      return refusal === undefined ? undefined : hookAnswerOf(name, named, refusal)
+    }
+    return hookOn(
+      hook,
+      async (input: unknown) => {
+        const payload = processPayloadOf(named as ProcessFieldsName, input)
+        if (named === 'SessionStart' && payload['source'] === 'compact') {
+          const started = isBefore ? compactionStarts.shift() : undefined
+          return started === undefined ? undefined : hookAnswerOf(name, named, started)
+        }
+        if (!isBefore) {
+          void raise(method, payload)
+          return undefined
+        }
+        const answer = await raise(method, payload)
+        return answer === undefined ? undefined : hookAnswerOf(name, named, answer)
+      },
+      isBefore ? failed : undefined,
+    )
   }
 
-  const listen = (method: string, args: readonly unknown[]): Disposable => {
-    const entry = listenerOf(name, method, args) as ProcessListener
+  const compactionStarts: HookFields[] = []
+
+  const compactionNote = async (e: Args<'session.compact'>, next: (e: Args<'session.compact'>) => Promise<SessionCompactResult>): Promise<SessionCompactResult> => {
+    const compacted = await next(e)
+    if (e.trigger === 'precompute' || compacted.skip !== undefined) return compacted
+    const model = e.agentId === undefined ? await claude.session.model() : undefined
+    const answer = await raise('beforeSessionStart', { session: current.id, cwd: current.cwd, ...defined({ task: e.agentId, model, title: current.title || undefined, contextTokenCount: compacted.tokensAfter }), source: 'compact' })
+    const { note, ...started } = answer ?? {}
+    if (Object.keys(started).length > 0) compactionStarts.push(started)
+    if (typeof note !== 'string') return compacted
+    if (!isGranted('prompt')) {
+      report('session:beforeSessionStart', 'The beforeSessionStart listener failed', new Error(`${name}: its note adds text Claude reads, which needs the prompt permission.`))
+      return compacted
+    }
+    return { ...compacted, messages: [...compacted.messages, { role: 'user', text: modNote(name, note), toolUses: [] }] }
+  }
+
+  const listen = (method: string, args: readonly unknown[], isEveryAgent = false): Disposable => {
+    const heard = listenerOf(name, method, args)
+    const entry = { ...heard, options: method === 'beforePermissionRequest' ? { ...heard.options, onFailure: 'refuse' } : heard.options, isEveryAgent } as ProcessListener
     const held = processListeners.get(method) ?? new Set()
     if (!processListeners.has(method)) {
       listenTo(method, method.replace(/^(on|before)/, ''))
@@ -501,10 +551,16 @@ export function createSessionsClient({ name, claude, report, isGranted, hookOn,
       Object.entries(processEvents).flatMap(([named, event]) => [`on${named}`, ...('before' in event ? [`before${named}`] : [])]).map((method) => [method, (...args: unknown[]) => listen(method, args)]),
     ) as ProcessOnMethods & ProcessBeforeMethods
 
-  const currentSession = Object.assign(sessionOf(() => current), processMethods())
+  const here = sessionOf(() => current)
+  const currentSession = Object.assign(here, processMethods(), { goal: Object.assign(here.goal, { beforeSessionStart: (...args: unknown[]) => listen('beforeSessionStart', args, true) }) })
   const every = eventMethods(() => ({}), false)
 
-  const answerBefore = async (session: string, event: BeforeEvent, change: SessionChange, isInProject: boolean) => (session === current.id || isGranted('conversation') ? combined(session, event, change, isInProject) : undefined)
+  const answerBefore = async (session: string, event: BeforeEvent, change: SessionChange, isInProject: boolean) => (mayDecide(session) ? combined(session, event, change, isInProject) : undefined)
+
+  const failedBefore = (session: string, event: BeforeEvent, change: SessionChange, isInProject: boolean, error: Error) => {
+    const asked = mayDecide(session) ? decidersOf(session, event, isInProject).filter((entry) => decides(entry, session, change)) : []
+    return asked.map((entry) => refusalOf(entry.options, beforeAnswerKeys[event], error)).find((answer) => answer !== undefined)
+  }
 
   return {
     sessions: {
@@ -537,6 +593,7 @@ export function createSessionsClient({ name, claude, report, isGranted, hookOn,
       }
     },
     answerBefore,
+    failedBefore,
     raise,
     listen,
     follow(next) {
@@ -561,8 +618,9 @@ export function createSessionsClient({ name, claude, report, isGranted, hookOn,
 export type ToolCheck = { readonly tool: string; readonly input: unknown; readonly tool_use_id?: string; readonly agentId?: string; readonly ceiling?: 'allow' | 'ask' | 'deny' }
 
 export type RouteOn = {
-  (event: 'tool.check', hook: (e: ToolCheck, next: (e: ToolCheck) => Promise<unknown>) => Promise<unknown>): Disposable
-  (event: 'command.run', hook: (e: Args<'command.run'>, next: (e: Args<'command.run'>) => Promise<CommandRunResult>) => Promise<CommandRunResult>): Disposable
+  (event: 'tool.check', hook: (e: ToolCheck, next: (e: ToolCheck) => Promise<unknown>) => Promise<unknown>, failed?: (e: ToolCheck, error: Error, next: (e: ToolCheck) => Promise<unknown>) => Promise<{ readonly decision: 'deny'; readonly reason: string } | undefined>): Disposable
+  (event: 'command.run', hook: (e: Args<'command.run'>, next: (e: Args<'command.run'>) => Promise<CommandRunResult>) => Promise<CommandRunResult>, failed?: (e: Args<'command.run'>, error: Error) => Promise<CommandRunResult | undefined>): Disposable
+  (event: 'session.compact', hook: (e: Args<'session.compact'>, next: (e: Args<'session.compact'>) => Promise<SessionCompactResult>) => Promise<SessionCompactResult>): Disposable
 }
 
 export const recordOf = (value: unknown): Readonly<Record<string, unknown>> => (typeof value === 'object' && value !== null && !Array.isArray(value) ? (value as Record<string, unknown>) : {})
@@ -659,9 +717,9 @@ export function processPayloadOf(named: ProcessFieldsName, input: unknown): Hook
   return { ...placementOf(fields), ...defined(processFields[named](fields)) }
 }
 
-function hookAnswerOf(named: string, answer: HookFields): HookFields | undefined {
+function hookAnswerOf(name: string, named: string, answer: HookFields): HookFields | undefined {
   const refuse = typeof answer['refuse'] === 'string' ? answer['refuse'] : undefined
-  const note = typeof answer['note'] === 'string' ? [answer['note']] : undefined
+  const note = typeof answer['note'] === 'string' ? [modNote(name, answer['note'])] : undefined
   if (named === 'SessionStart') return defined({ additionalContext: note, sessionTitle: answer['title'], reloadSkills: answer['reloadSkills'] === true ? true : undefined, initialUserMessage: answer['firstPrompt'] })
   if (named === 'ModelChange') {
     if (refuse !== undefined) return { permissionDecision: 'deny', permissionDecisionReason: refuse }

package/src/runtime/toaster.ts

@@ -180,6 +180,8 @@ export function createToaster(claude: Claude, name: string, version: () => strin
     const hides = `${version() ?? ''}\n${message}\n${error === undefined ? '' : describe(error)}`
     if (hidden.get(id) === hides) return id
     hidden.delete(id)
+    const shown = entries.get(id)
+    if (shown?.hides === hides && shown.trying === undefined && shown.options.description === description) return id
     const stack = error instanceof Error && error.stack !== undefined ? `\n\n${error.stack}` : ''
     const details = async () => {
       const modVersion = await claude.fs

package/src/session/context/turn/message/message.ts

@@ -1,11 +1,11 @@
 import { isObject } from '../../../../records.js'
 import { Task } from '../../../goal/task.js'
 import { InstructionFile, isRulePath } from './instruction-file.js'
-import { Note } from './note.js'
+import { modNote, modNoteBlock, modNotesIn, Note } from './note.js'
 import { Notice } from './notice.js'
 import { Prompt } from './prompt.js'
 import { Reply } from './reply.js'
-import { senderOf } from './sender.js'
+import { Mod, senderOf } from './sender.js'
 import { Skill } from './skill.js'
 import { ToolCall, type CallFiles } from './tool-call.js'
 import { ToolResult } from './tool-result.js'
@@ -108,8 +108,11 @@ export function messagesOf(row: Row, isInTask: boolean): Unplaced[] {
 function unplacedOf(row: Row, isInTask: boolean): Unplaced[] {
   const base = { id: row.id, at: row.at }
   const text = textOf(row.content).trim()
+  const notesFrom = (each: readonly { readonly mod: string; readonly text: string }[]): Unplaced[] => each.map((note) => ({ ...base, type: Note, text: note.text, from: { type: Mod, name: note.mod } }))
   if (row.type === 'system') return row.name === 'turn_duration' || row.name === 'compact_boundary' || text === '' ? [] : [{ ...base, type: Notice, text }]
+  if (row.type === 'attachment' && row.name === 'hook_additional_context') return notesFrom(row.content.flatMap((entry) => modNotesIn(typeof entry === 'string' ? entry : textOf([entry]))))
   if (row.type === 'attachment') return row.name === 'nested_memory' ? [{ ...base, type: InstructionFile, path: row.path ?? '', text, isRule: isRulePath(row.path ?? '') }] : []
+  if (isModNotesRow(row)) return notesFrom(modNotesIn(text))
   if (row.type === 'assistant') {
     return row.content.filter(isObject).flatMap((block): Unplaced[] => {
       if (block['type'] === 'text' && typeof block['text'] === 'string' && block['text'].trim() !== '') return [{ ...base, type: Reply, text: block['text'].trim() }]
@@ -128,7 +131,29 @@ function unplacedOf(row: Row, isInTask: boolean): Unplaced[] {
   return prompt === undefined ? [] : [{ ...base, type: Prompt, text: prompt, from: senderOf(row.origin, isInTask) }]
 }
 
+function isModNotesRow(row: Row): boolean {
+  const text = textOf(row.content)
+  return row.type === 'user' && !row.content.some(isToolResultBlock) && modNotesIn(text).length > 0 && text.replace(modNoteBlock, '').trim() === ''
+}
+
+function withNoteTexts(entries: readonly unknown[], texts: ReadonlyMap<number, string>): unknown[] {
+  let index = -1
+  const replaced = (text: string) =>
+    text.replace(modNoteBlock, (whole, mod: string) => {
+      index += 1
+      const changed = texts.get(index)
+      if (changed === undefined) return whole
+      return changed === '' ? '' : modNote(mod, changed)
+    })
+  return entries.map((entry) => {
+    if (typeof entry === 'string') return replaced(entry)
+    return isObject(entry) && entry['type'] === 'text' && typeof entry['text'] === 'string' ? { ...entry, text: replaced(entry['text']) } : entry
+  })
+}
+
 export function withTexts(row: Row, texts: ReadonlyMap<number, string>): readonly unknown[] {
+  if (row.type === 'attachment' && row.name === 'hook_additional_context') return withNoteTexts(row.content, texts)
+  if (isModNotesRow(row)) return keepingMedia(row.content, withNoteTexts([textOf(row.content)], texts)[0] as string)
   if (row.type === 'assistant') {
     let index = -1
     return row.content.map((block) => {

package/src/session/context/turn/message/note.ts

@@ -1,3 +1,4 @@
+import { pluginName } from '../../../../records.js'
 import type { MessageOf } from './message.js'
 import type { Sender } from './sender.js'
 
@@ -7,3 +8,18 @@ export type Note = MessageOf<typeof Note> & {
   readonly text: string
   readonly from: Sender
 }
+
+export const modNoteBlock = new RegExp(`<(${pluginName.source.slice(1, -1)})_mod>\\n([\\s\\S]*?)\\n</\\1_mod>`, 'g')
+
+export function modNote(mod: string, text: string): string {
+  return `<${mod}_mod>\n${text}\n</${mod}_mod>`
+}
+
+export function modNotesIn(text: string): { readonly mod: string; readonly text: string }[] {
+  return [...text.matchAll(modNoteBlock)].map((match) => ({ mod: match[1] as string, text: match[2] as string }))
+}
+
+export function untagged(text: string): string {
+  const notes = modNotesIn(text)
+  return notes.length === 0 ? text : notes.map((note) => note.text).join('\n\n')
+}

package/src/session/session.ts

@@ -120,7 +120,6 @@ export type OnMethods = { readonly [Name in EventName as `on${Name}`]: OnMethod<
 
 export type BeforeMethods = { readonly [Name in BeforeName as `before${Name}`]: BeforeMethod<PayloadOf<Name>, AnswerOf<Name>> }
 
-
 export type RecordPart = OnMethods &
   BeforeMethods & {
     search(text: string, matcher?: Matcher<Message>): AsyncIterable<Message>
@@ -327,7 +326,7 @@ export type ProcessOnMethods = { readonly [Name in ProcessName as `on${Name}`]:
 
 export type ProcessBeforeMethods = { readonly [Name in keyof ProcessAnswer as `before${Name}`]: BeforeMethod<ProcessAsked[Name], ProcessAnswer[Name]> }
 
-export type CurrentSession = Session & ProcessOnMethods & ProcessBeforeMethods
+export type CurrentSession = Omit<Session, 'goal'> & ProcessOnMethods & ProcessBeforeMethods & { readonly goal: Goal & Pick<ProcessBeforeMethods, 'beforeSessionStart'> }
 
 export type SessionScope = {
   readonly running?: boolean

package/src/testing/fake-claude.ts

@@ -1,6 +1,7 @@
 import type { EventResult, Timer } from 'claude-code'
 import { isObject } from '../records.js'
 import type { Claude } from '../runtime/claude.js'
+import { untagged } from '../session/context/turn/message/note.js'
 import { elements } from './fake-elements.js'
 import { fakeFiles } from './fake-files.js'
 
@@ -21,7 +22,7 @@ export type Fakes = {
   prompt: { submit?: Claude['prompt']['submit'] }
   model: { complete?: Claude['model']['complete'] }
   agent: { list?: Claude['agent']['list']; spawn?: Claude['agent']['spawn'] }
-  clock: { after?: Claude['clock']['after']; every?: Claude['clock']['every'] }
+  clock: { now?: Claude['clock']['now']; after?: Claude['clock']['after']; every?: Claude['clock']['every'] }
   cmod: { call?: Claude['cmod']['call'] }
   tool: { call?: Claude['tool']['call'] }
 }
@@ -79,7 +80,7 @@ export function fakeClaude(plugin: { readonly name: string; readonly root: strin
   }
 
   const appendNote: Claude['session']['append'] = async ({ message }) => {
-    shown.notes.push(message.content.map((block) => (typeof block['text'] === 'string' ? block['text'] : '')).join(''))
+    shown.notes.push(untagged(message.content.map((block) => (typeof block['text'] === 'string' ? block['text'] : '')).join('')))
     return { message, uuid: `note-${shown.notes.length}` }
   }
   const submitPrompt: Claude['prompt']['submit'] = async ({ text }) => {
@@ -175,7 +176,7 @@ export function fakeClaude(plugin: { readonly name: string; readonly root: strin
       keys: async () => [...store.keys()],
     },
     clock: {
-      now: async () => Date.now(),
+      now: () => (fakes.clock.now === undefined ? Promise.resolve(Date.now()) : fakes.clock.now()),
       after: faked('clock.after', () => fakes.clock.after ?? realTimer),
       every: faked('clock.every', () => fakes.clock.every ?? idleInterval),
     },