@cmodjs/core 2.1.0 → 3.0.0

package/src/runtime/conversations.ts

@@ -1,7 +1,7 @@
 import type { Args, EventResult, Frozen } from 'claude-code'
 import { consentPath, dataFolder, isObject, parseConsent } from '../records.js'
 import { Message, rowOfAppend, type Row } 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 } from '../session/context/turn/message/sender.js'
 import { createConversation, emptyConversation, type Conversation, type ConversationState, type ContextData, type SessionChange, type SessionData, type TaskData, type TurnData, type TurnEnding } from '../session/conversation.js'
 import { Session, UsageChange, type BeforeEvent, type Surface, type SessionSend, type TaskStartArgs, type ToolCallArgs } from '../session/session.js'
@@ -9,18 +9,19 @@ import { GoalChange } from '../session/goal/goal.js'
 import { receivedMatcher } from '../utils/matcher.js'
 import { ifMissing } from '../utils/paths.js'
 import { formatExit, messageOf } from '../utils/text.js'
-import { foldBefore, installBefore, relayOf, type Place } from './before.js'
+import { beforeAnswerKeys, foldBefore, installBefore, relayOf, type Place } from './before.js'
 import type { Claude } from './claude.js'
 import { cmodPluginName } from './dependencies.js'
 import { readLines, runCmod } from './programs.js'
-import type { Router } from './router.js'
-import { actPermission, conversationMethods, everySession, isAct, isHeardBy, resultOf, spawnTask, usageOf, type Act, type Subscription } from './sessions.js'
+import type { RoutedHook, Router } from './router.js'
+import { PassedTimeout } from './deadline.js'
+import { actPermission, conversationMethods, everySession, isAct, isHeardBy, isInScope, resultOf, spawnTask, usageOf, type Act, type Subscription } from './sessions.js'
 
 type Request = Readonly<Record<string, unknown>>
 
 type Heard = { readonly event: Subscription['event']; readonly matcher: unknown }
 
-type Watch = { readonly mod: string; readonly target: string; readonly project: string; readonly events: readonly string[] }
+type Watch = { readonly mod: string; readonly target: string; readonly project: string; readonly events: readonly string[]; readonly refusing?: readonly Subscription[] }
 
 type Watcher = Watch & { readonly from: string }
 
@@ -37,6 +38,8 @@ const bufferedTaskRows = 200
 
 const beforeDeadlineMs = 5000
 
+const awayFoldMs = 8000
+
 const livenessMs = 5000
 
 
@@ -185,7 +188,7 @@ export function serveConversations({ claude, router, store, project, report }: {
           reject(error)
         },
       }
-      const timer = deadlineMs === undefined ? watchLife(settle, to) : claude.clock.after(deadlineMs, () => settle.reject(new Error(`session ${to} did not answer within ${deadlineMs / 1000} s`)))
+      const timer = deadlineMs === undefined ? watchLife(settle, to) : claude.clock.after(deadlineMs, () => settle.reject(new PassedTimeout(`session ${to} did not answer within ${deadlineMs / 1000} s`)))
       asked.set(id, settle)
       post(to, { ...relay, id, from: session }).catch((error: unknown) => settle.reject(error instanceof Error ? error : new Error(messageOf(error))))
     })
@@ -240,11 +243,24 @@ export function serveConversations({ claude, router, store, project, report }: {
     return claude.cmod.call({ to: mod, method: conversationMethods.before, input: { session: from, event, change, isInProject } })
   }
 
-  const askAway = async (watcher: Watcher, event: BeforeEvent, change: SessionChange) => {
+  const isUnderHere = (task: string, ancestor: string) => {
+    for (let at: string | undefined = task, steps = 0; at !== undefined && steps < 64; at = conversation.state.tasks[at]?.parent, steps += 1) if (at === ancestor) return true
+    return false
+  }
+
+  const refuses = (watcher: Watcher, event: BeforeEvent, change: SessionChange) =>
+    beforeAnswerKeys[event].includes('refuse') && (watcher.refusing ?? []).some(({ event: heard, matcher, scope }) => isInScope(scope ?? {}, session, change, isUnderHere) && isHeardBy(heard, matcher === undefined ? undefined : receivedMatcher(matcher), change))
+
+  const askAway = async (watcher: Watcher, event: BeforeEvent, change: SessionChange, endsAt: number) => {
     try {
-      return await ask(watcher.from, { kind: 'before', mod: watcher.mod, event, change, project: project() }, beforeDeadlineMs)
+      const leftMs = Math.min(beforeDeadlineMs, endsAt - (await claude.clock.now()))
+      if (leftMs <= 0) throw new PassedTimeout(`the ${awayFoldMs / 1000} s cmod waits on other sessions ran out before session ${watcher.from} was asked`)
+      return await ask(watcher.from, { kind: 'before', mod: watcher.mod, event, change, project: project() }, leftMs)
     } catch (error) {
-      if (await isRunning(watcher.from)) throw error
+      if (await isRunning(watcher.from)) {
+        if (error instanceof PassedTimeout && refuses(watcher, event, change)) return { refuse: `${watcher.mod}: ${error.message}` }
+        throw error
+      }
       watchers = watchers.filter((each) => each.from !== watcher.from)
       claude.ui.log(`cmod: session ${watcher.from} ended without clearing its before listeners, so they are cleared now`, { to: 'debug' })
       await claude.fs.write(`${watches}/${watcher.from}.json`, '[]')
@@ -264,13 +280,20 @@ export function serveConversations({ claude, router, store, project, report }: {
         await Promise.all([starting, watching])
         return deciders(event).length > 0
       },
-      decide: (event, change) =>
-        foldBefore(
-          event,
-          change,
-          deciders(event).map((watcher) => (latest: SessionChange) => (watcher.from === session ? askHere(watcher.mod, event, latest) : askAway(watcher, event, latest))),
-          (error) => report(`before:${event}`, `Passed the ${event} on without a mod's answer`, error),
-        ),
+      fold: () => {
+        let endsAt: Promise<number> | undefined
+        return (event, change) =>
+          foldBefore(
+            event,
+            change,
+            deciders(event).map((watcher) => async (latest: SessionChange) => {
+              if (watcher.from === session) return askHere(watcher.mod, event, latest)
+              endsAt ??= claude.clock.now().then((now) => now + awayFoldMs)
+              return askAway(watcher, event, latest, await endsAt)
+            }),
+            (error) => report(`before:${event}`, `Passed the ${event} on without a mod's answer`, error),
+          )
+      },
     },
   })
 
@@ -321,22 +344,24 @@ export function serveConversations({ claude, router, store, project, report }: {
     return next(e)
   })
 
-  router.add('session.append', async (e, next) => {
+  const recordAppend: RoutedHook<'session.append'> = async (e, next) => {
     const kept = await next(e)
     if (kept.deny !== undefined || session === '') return kept
     const cwd = e.message.type === 'assistant' ? await claude.session.cwd() : ''
     void take(rowOfAppend({ uuid: kept.uuid, door: e.door, origin: e.origin, message: kept.message }, new Date().toISOString(), cwd), e.agentId).catch((error: unknown) => report('append', 'Missed a message', error))
     return kept
-  })
+  }
+  router.add('session.append', recordAppend, (e, _error, next) => recordAppend(e, next))
 
-  router.add('session.compact', async (e, next) => {
+  const recordCompaction: RoutedHook<'session.compact'> = async (e, next) => {
     const compacted = await next(e)
     if (e.trigger === 'precompute' || compacted.skip !== undefined || session === '') return compacted
     const at = new Date().toISOString()
     const boundary: Row = { id: `compact:${e.agentId ?? session}:${at}`, at, type: 'system', name: 'compact_boundary', isMeta: false, isSummary: false, content: [] }
     void take(boundary, e.agentId).catch((error: unknown) => report('compact', 'Missed a compaction', error))
     return compacted
-  })
+  }
+  router.add('session.compact', recordCompaction, (e, _error, next) => recordCompaction(e, next))
 
   router.add('session.measure', async (e, next) => {
     const measured = await next(e)
@@ -344,7 +369,7 @@ export function serveConversations({ claude, router, store, project, report }: {
     return measured
   })
 
-  router.add('agent.spawn', async (e, next) => {
+  const recordSpawn: RoutedHook<'agent.spawn'> = async (e, next) => {
     const spawned = await next(e)
     if (spawned.deny !== undefined || spawned.agentId === undefined) return spawned
     const id = spawned.agentId
@@ -355,7 +380,8 @@ export function serveConversations({ claude, router, store, project, report }: {
     waitingRows.delete(id)
     for (const row of waiting) dispatch(session, conversation.add(row, id))
     return spawned
-  })
+  }
+  router.add('agent.spawn', recordSpawn, (e, _error, next) => recordSpawn(e, next))
 
   router.add('session.receive', async (e, next) => {
     const sent = relayOf(e)
@@ -398,13 +424,13 @@ export function serveConversations({ claude, router, store, project, report }: {
     await checkAct(caller, action, input)
     await starting
     if (action === 'abort') return abortTurn(input, task)
-    if (task !== undefined) return performInTask(action, input, task)
+    if (task !== undefined) return performInTask(caller, action, input, task)
     if (action === 'usage') return usageOf(claude)
     if (action === 'surfaces') return [...(await claude.session.surfaces())] satisfies Surface[]
     if (action === 'send') {
       const { type, text, as } = input as SessionSend
       if (as === Session) throw new Error(`session ${session} cannot send as itself to itself.`)
-      const delivered = type === Note ? await claude.session.append({ message: { type: 'user', content: [{ type: 'text', text }] } }) : await claude.prompt.submit({ text, ...(as === Person ? { asUser: true } : {}) })
+      const delivered = type === Note ? await claude.session.append({ message: { type: 'user', content: [{ type: 'text', text: modNote(caller, text) }] } }) : await claude.prompt.submit({ text, ...(as === Person ? { asUser: true } : {}) })
       if ('deny' in delivered && typeof delivered.deny === 'string') throw new Error(`Claude Code refused the note: ${delivered.deny}`)
       if ('drop' in delivered && typeof delivered.drop === 'string') throw new Error(`Claude Code dropped the prompt: ${delivered.drop}`)
       return null
@@ -424,13 +450,14 @@ export function serveConversations({ claude, router, store, project, report }: {
     return null
   }
 
-  const performInTask = async (action: Act, input: unknown, task: string): Promise<unknown> => {
+  const performInTask = async (caller: string, action: Act, input: unknown, task: string): Promise<unknown> => {
     const running = conversation.state.tasks[task]
     if (action === 'usage') return json(['history', 'usage', session, '--task', task])
     if (action === 'surfaces') return running === undefined || running.closedAt !== undefined ? [] : [...(await claude.session.surfaces())]
     if (action !== 'send') throw new Error(`cmod: ${action} runs only on a session's own main loop.`)
     if (running === undefined || running.closedAt !== undefined) throw ended(task)
-    const sent = await claude.session.send({ to: { agentId: task }, text: (input as SessionSend).text })
+    const { type, text } = input as SessionSend
+    const sent = await claude.session.send({ to: { agentId: task }, text: type === Note ? modNote(caller, text) : text })
     if (sent.isDelivered !== true) throw ended(task)
     return null
   }
@@ -567,7 +594,7 @@ export function serveConversations({ claude, router, store, project, report }: {
       if (caller === undefined) throw new Error('cmod hears no caller for this before listener.')
       const target = String(request['session'])
       const list = Array.isArray(request['subscriptions']) ? (request['subscriptions'] as readonly Subscription[]) : []
-      ownWatches.set(`${caller}\n${target}`, { mod: caller, target, project: project(), events: [...new Set(list.map(({ event }) => event))] })
+      ownWatches.set(`${caller}\n${target}`, { mod: caller, target, project: project(), events: [...new Set(list.map(({ event }) => event))], refusing: list.filter((each) => each.onFailure === 'refuse') })
       await publishWatches()
       return null
     },

package/src/runtime/hooks.ts

@@ -1,7 +1,7 @@
 import type { ClassicHookEvent, ClassicHookInputs } from 'claude-code'
 import { configFolders } from '../records.js'
 import type { Claude } from './claude.js'
-import type { RoutedHook } from './router.js'
+import type { RoutedFailure, RoutedHook } from './router.js'
 import type { Failure } from './toaster.js'
 import { callEffects, type CallBase, type FileAccess } from '../utils/call-effects.js'
 import { dynamicPattern } from '../utils/parse-shell.js'
@@ -51,6 +51,14 @@ export function classicHook<H extends Hook>(event: H, hook: HookListener<H>, rep
   return routed as unknown as RoutedHook<RoutedEvent>
 }
 
+export function classicFailure<H extends Hook>(failed: (input: ClassicHookInputs[H], error: Error) => HookFields | undefined | Promise<HookFields | undefined>): RoutedFailure<RoutedEvent> {
+  const routed = async (e: unknown, error: Error, next: (e: unknown) => Promise<unknown>) => {
+    const ours = await failed(e as ClassicHookInputs[H], error)
+    return ours === undefined ? undefined : mergeClassic((await next(e)) as HookFields, ours)
+  }
+  return routed as unknown as RoutedFailure<RoutedEvent>
+}
+
 const frontmatter = /^---\r?\n[\s\S]*?\r?\n---[ \t]*(?:\r?\n|$)/
 
 const baseDirectoryLine = /^Base directory for this skill: [^\n]*\n\n/

package/src/runtime/lifecycle.ts

@@ -1,4 +1,4 @@
-import type { Args, EventResult, Frozen, HookBudget, PluginOptions, RenderElement, Timer } from 'claude-code'
+import type { Args, ClassicHookInputs, EventResult, Frozen, HookBudget, HookFailure, PluginOptions, RenderElement, Timer } from 'claude-code'
 import type { Step } from '../installer.js'
 import type { Allowed, FileChange, Disposable, Imports, Mod, ModDefinition, PaneHandle, SettingsFile, SettingsFileChange, SettingsFileChangeListener, Toast } from '../mod.js'
 import type { Options, OptionValues } from '../options.js'
@@ -12,7 +12,7 @@ import { bind } from './bound.js'
 import { serveConversations } from './conversations.js'
 import { answerCall, answeringOwnCalls, cmodPluginName, dependencyCalls, withBareRefusals } from './dependencies.js'
 import { keepEngine } from './engine.js'
-import { classicHook, userSkillHook, type Hook, type HookListener, type RoutedEvent } from './hooks.js'
+import { classicFailure, classicHook, userSkillHook, type Hook, type HookFields, type HookListener, type RoutedEvent } from './hooks.js'
 import type { PermissionRoutes } from './permission-check.js'
 import { checkedAnswer, checkingGrants, checkSettings, checksAnswers, checkWrite, isCovered, itemOf, passedDown, programAddresses, type AnswerCheck, type Grants } from './grants.js'
 import { cmodError, lastLineOf, locatingPrograms, readLines, type Programs } from './programs.js'
@@ -21,7 +21,7 @@ import { fitsOption } from '../options.js'
 import { createInstaller } from './installer.js'
 import { createOptions, MissingOptions } from './options.js'
 import { createRouter, type Router, type RouterNext } from './router.js'
-import { conversationMethods, createSessionsClient } from './sessions.js'
+import { conversationMethods, createSessionsClient, type SessionsClient } from './sessions.js'
 import type { SessionChange } from '../session/conversation.js'
 import type { BeforeEvent } from '../session/session.js'
 import { matches } from '../utils/matcher.js'
@@ -52,6 +52,7 @@ export type Lifecycle<State extends object> = {
   readonly toasts: readonly ShownToast[]
   start(claude: Claude, read: (claude: Claude) => Promise<Plugin>): Promise<void>
   route<N extends RoutedEvent>(event: N, e: Frozen<Args<N>>, next: RouterNext<N>): Promise<EventResult<N>>
+  caught<N extends RoutedEvent>(event: N, e: Frozen<Args<N>>, next: RouterNext<N>, failure: HookFailure): Promise<EventResult<N>>
   raise(method: string, payload: Readonly<Record<string, unknown>>): Promise<unknown>
 }
 
@@ -72,7 +73,7 @@ type ActiveMod<State extends object, Declared extends Options> = {
   readonly mod: Mod<State, Declared>
   readonly added: readonly string[]
   readonly imports: Imports
-  readonly raise: (method: string, payload: Readonly<Record<string, unknown>>) => Promise<unknown>
+  readonly raise: SessionsClient['raise']
 }
 
 
@@ -88,7 +89,9 @@ const cmodWaitMs = 60_000
 
 const cmodSlowCheckMs = 10_000
 
-const startHoldMs = (10_000 satisfies HookBudget['ms']) - 1_000
+const hookMs = 10_000 satisfies HookBudget['ms']
+
+const startHoldMs = hookMs - 1_000
 
 const dependencyCallMs = 30_000
 
@@ -169,7 +172,7 @@ export function createLifecycle<State extends object, Declared extends Options =
   let activation: Promise<void> | undefined
   let mod: Mod<State> | undefined
   let imports: Imports | undefined
-  let raise: ActiveMod<State, Declared>['raise'] | undefined
+  let raise: SessionsClient['raise'] | undefined
   let failure: unknown
   let pluginOptions = options
   const installer = createInstaller(definition.name, () => claude())
@@ -628,6 +631,16 @@ export function createLifecycle<State extends object, Declared extends Options =
       if (event !== 'ui.render' || render.component !== 'AbovePrompt' || runtime === undefined) return answer
       return runtime.toaster.draw((await answer) as EventResult<'ui.render'>, runtime.claude.ui.resolve(render), render.props, render.requestId) as EventResult<N>
     },
+    async caught<N extends RoutedEvent>(event: N, e: Frozen<Args<N>>, next: RouterNext<N>, { kind, message }: HookFailure): Promise<EventResult<N>> {
+      const call = e as Frozen<Args<'cmod.call'>>
+      const isAsk = event === 'cmod.call' && call.to === definition.name && beforeAskOf(call) !== undefined
+      const reasons: Readonly<Record<string, string>> = { timeout: `it ran past the ${hookMs / 1000} s Claude Code gives a hook`, throw: message ?? 'it threw' }
+      const reason = reasons[kind]
+      if (reason === undefined) return isAsk ? ({ value: null } as EventResult<N>) : next(e)
+      const error = new Error(reason)
+      toastFailure({ id: `stopped:${event}`, message: `Claude Code stopped its ${event.replace(/^classic\./, '')} hook`, error })
+      return router.dispatchFailure(event, e, error, next)
+    },
   }
 }
 
@@ -704,7 +717,8 @@ async function createMod<State extends object, Declared extends Options>(definit
     }))
   const modState = createState<State>({ name: definition.name, initial: definition.state ?? {}, session, root, claude, report, changed: area.changed, forkParent })
   const modOptions = createOptions({ name: definition.name, declared: definition.options ?? {}, fromClaude: runtime.options, claude, report, changed: modState.changed })
-  const hookOn = <H extends Hook>(hook: H, listener: HookListener<H>): Disposable => router.add(`classic.${hook}`, classicHook(hook, listener, report))
+  const hookOn = <H extends Hook>(hook: H, listener: HookListener<H>, failed?: (input: ClassicHookInputs[H], error: Error) => HookFields | undefined): Disposable =>
+    router.add(`classic.${hook}`, classicHook(hook, listener, report), failed === undefined ? undefined : classicFailure(failed))
   const expand = (path: string) => (homePrefix.test(path) ? resolvedPath(path, places) : path)
   const settingsFile = (source: 'user' | 'project' | 'local'): SettingsFile => ({
     read: () => checked.settings.read({ source }),
@@ -718,8 +732,8 @@ async function createMod<State extends object, Declared extends Options>(definit
     claude: checked,
     report: (id, message, error) => report({ id, message, error }),
     isGranted: (permission) => flag(permission),
-    hookOn: (hook, listener) => hookOn(hook as Hook, listener as HookListener<Hook>),
-    routeOn: (event, hook) => router.add(event, hook as never),
+    hookOn: (hook, listener, failed) => hookOn(hook as Hook, listener as HookListener<Hook>, failed),
+    routeOn: (event: RoutedEvent, hook: unknown, failed?: unknown) => router.add(event, hook as never, failed as never),
     permissionRoutes: runtime.permissionRoutes,
   })
   let followed: Parameters<typeof client.follow>[0] | undefined
@@ -944,10 +958,8 @@ async function createMod<State extends object, Declared extends Options>(definit
       client.changed(changedSession, change, isInProject !== false)
       return { value: null }
     }
-    if (e.method === conversationMethods.before && call.caller === cmodPluginName) {
-      const { session: asking, event, change, isInProject } = e.input as { readonly session: string; readonly event: BeforeEvent; readonly change: SessionChange; readonly isInProject?: boolean }
-      return { value: (await client.answerBefore(asking, event, change, isInProject !== false)) ?? null }
-    }
+    const ask = beforeAskOf(call)
+    if (ask !== undefined) return { value: (await client.answerBefore(ask.session, ask.event, ask.change, ask.isInProject)) ?? null }
     if (e.method === settingsPagesMethod) return { value: [...pages].map(([id, { title }]) => ({ id, title })) }
     if (e.method === openPageMethod) {
       await settingsPages.open(String(e.input))
@@ -955,6 +967,10 @@ async function createMod<State extends object, Declared extends Options>(definit
     }
     const served = await conversations?.answer(call)
     return served ?? answerCall(definition.name, api, e)
+  }, (e, error) => {
+    if (e.to !== definition.name) return undefined
+    const ask = beforeAskOf(e)
+    return ask === undefined ? { deny: `${definition.name}: ${error.message}` } : { value: client.failedBefore(ask.session, ask.event, ask.change, ask.isInProject, error) ?? null }
   })
   const agents = toolCalls(claude, router)
   keepEngine(mod, { claude: checked, router, toolCalls: agents, report, hasPermissionCheck: () => runtime.permissionRoutes() !== undefined })
@@ -997,6 +1013,14 @@ function checkedMs(name: string, subject: string, ms: number): number {
   return ms
 }
 
+type BeforeAsk = { readonly session: string; readonly event: BeforeEvent; readonly change: SessionChange; readonly isInProject: boolean }
+
+function beforeAskOf(call: Frozen<Args<'cmod.call'>> & { readonly caller?: string }): BeforeAsk | undefined {
+  if (call.method !== conversationMethods.before || call.caller !== cmodPluginName) return undefined
+  const { session, event, change, isInProject } = call.input as Omit<BeforeAsk, 'isInProject'> & { readonly isInProject?: boolean }
+  return { session, event, change, isInProject: isInProject !== false }
+}
+
 async function failsAs(subject: string, step: () => unknown): Promise<void> {
   try {
     await step()

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,36 +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
+  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)
         },
       }
     },
     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)
+    },
   }
 }