@cmodjs/core 2.0.0 → 2.0.1

package/src/runtime/lifecycle.ts

@@ -13,6 +13,7 @@ import { serveConversations } from './conversations.js'
 import { answerCall, answeringOwnCalls, cmodPluginName, dependencyCalls, withBareRefusals } from './dependencies.js'
 import { keepEngine } from './engine.js'
 import { classicHook, permissionEvents, userSkillHook, type Hook, 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'
 import { createModFiles, resolvedPath, type Places } from './metadata.js'
@@ -63,7 +64,7 @@ type ModRuntime = {
   readonly steps: Steps
   readonly granted: ReadonlySet<string>
   readonly refreshGrants: () => Promise<void>
-  readonly checksPermissions: () => boolean
+  readonly permissionRoutes: () => PermissionRoutes | undefined
   readonly options: PluginOptions
 }
 
@@ -85,6 +86,8 @@ const cmodCheckMs = 1000
 
 const cmodWaitMs = 60_000
 
+const cmodSlowCheckMs = 10_000
+
 const startHoldMs = (10_000 satisfies HookBudget['ms']) - 1_000
 
 const dependencyCallMs = 30_000
@@ -153,7 +156,7 @@ async function cmodVersion(claude: Claude): Promise<string | undefined> {
 
 export function createLifecycle<State extends object, Declared extends Options = Options>(
   definition: ModDefinition<State, string, Declared>,
-  checksPermissions: () => boolean = () => true,
+  permissionRoutes: () => PermissionRoutes | undefined = () => undefined,
   options: PluginOptions = {},
   asksPerson = true,
 ): Lifecycle<State> {
@@ -319,7 +322,7 @@ export function createLifecycle<State extends object, Declared extends Options =
   const activate = async (): Promise<void> => {
     if (runtime === undefined || plugin === undefined) return
     const activeRouter = createRouter()
-    const active = await createMod(definition, { ...runtime, router: activeRouter, dataFolder: dataFolder(plugin.store, plugin.name), store: plugin.store, steps: plugin.steps, granted, refreshGrants, checksPermissions, options: pluginOptions }).catch(async (error: unknown) => {
+    const active = await createMod(definition, { ...runtime, router: activeRouter, dataFolder: dataFolder(plugin.store, plugin.name), store: plugin.store, steps: plugin.steps, granted, refreshGrants, permissionRoutes, options: pluginOptions }).catch(async (error: unknown) => {
       if (error instanceof MissingOptions && (await askOptions(error))) return undefined
       fail(messageOf(error), error instanceof MissingOptions ? `Set ${error.keys.length === 1 ? 'it' : 'them'} in /config.` : undefined, begin)
       throw error
@@ -335,12 +338,18 @@ export function createLifecycle<State extends object, Declared extends Options =
     void runSteps(active.mod).catch((error: unknown) => toastFailure({ id: 'cmod:steps', message: 'Its installer stopped', error }))
     const missed = missedSessionStart
     missedSessionStart = undefined
-    const lateAnswer = missed === undefined ? {} : await activeRouter.dispatch('classic.SessionStart', missed, async () => ({})).catch((error: unknown) => {
+    const replay = (e: Frozen<Args<'classic.SessionStart'>>) => (definition.name === cmodPluginName ? activeRouter.dispatch('classic.SessionStart', e, async () => ({})) : checkedRoute('classic.SessionStart', e, async () => ({})))
+    const lateAnswer = missed === undefined ? {} : await replay(missed).catch((error: unknown) => {
       toastFailure({ id: 'classic.SessionStart', message: 'The SessionStart hook failed', error })
       return {}
     })
-    if (Object.keys(lateAnswer).length > 0) {
-      runtime.claude.ui.log(`${definition.name} started after Claude Code's SessionStart, so Claude Code did not read the answer of its SessionStart hooks.`, { to: 'debug' })
+    const { additionalContext, ...unread } = lateAnswer as { readonly additionalContext?: readonly string[] } & Record<string, unknown>
+    for (const text of additionalContext ?? []) {
+      const added = await runtime.claude.session.append({ message: { type: 'user', content: [{ type: 'text', text }] } })
+      if (added.deny !== undefined) runtime.claude.ui.log(`${definition.name}: Claude Code refused its SessionStart note: ${added.deny}`, { to: 'debug' })
+    }
+    if (Object.keys(unread).length > 0) {
+      runtime.claude.ui.log(`${definition.name} started after Claude Code's SessionStart, so Claude Code did not read ${Object.keys(unread).join(', ')} from its SessionStart hooks.`, { to: 'debug' })
     }
     const version = plugin.version ?? ''
     const announced = announcedOf(await runtime.claude.store.get(announcedKey))
@@ -422,27 +431,31 @@ export function createLifecycle<State extends object, Declared extends Options =
       timer.cancel()
       longWait.cancel()
     }
-    const timer = claude().clock.every(cmodCheckMs, () => {
-      check ??= cmodVersion(claude())
-        .then((version) => {
-          check = undefined
-          latest = version
-          if (!fits(version)) return
-          stop()
-          return install()
-        })
-        .catch((error: unknown) => {
-          stop()
-          report(error)
-        })
-    })
-    const longWait = claude().clock.after(cmodWaitMs, () =>
+    const poll = (ms: number) =>
+      claude().clock.every(ms, () => {
+        check ??= cmodVersion(claude())
+          .then((version) => {
+            check = undefined
+            latest = version
+            if (!fits(version)) return
+            stop()
+            return install()
+          })
+          .catch((error: unknown) => {
+            stop()
+            report(error)
+          })
+      })
+    let timer = poll(cmodCheckMs)
+    const longWait = claude().clock.after(cmodWaitMs, () => {
+      timer.cancel()
+      timer = poll(cmodSlowCheckMs)
       installing(
         latest === undefined
           ? "Still waiting for cmod to download cmod. See cmod's own line."
           : `PATH finds cmod ${latest}, and ${definition.name} needs cmod ${oldestCmodFor(plugin?.steps ?? {})} or later. Run npm i -g @cmodjs/cli, or put ~/.local/bin ahead of the old cmod on PATH.`,
-      ),
-    )
+      )
+    })
   }
 
   const bootstrap = async (root: string) => {
@@ -595,7 +608,10 @@ export function createLifecycle<State extends object, Declared extends Options =
       const isCallToThisMod = event === 'cmod.call' && (e as Frozen<Args<'cmod.call'>>).to === definition.name
       if (event === 'cmod.call' && !isCallToThisMod) return next(e)
       await (event === 'classic.SessionStart' || isCallToThisMod ? holdUntilStarted() : whenActive())
-      if (event === 'classic.SessionStart' && phase !== 'active') missedSessionStart = e as Frozen<Args<'classic.SessionStart'>>
+      if (event === 'classic.SessionStart' && phase !== 'active') {
+        missedSessionStart = e as Frozen<Args<'classic.SessionStart'>>
+        return next(e)
+      }
       if (isCallToThisMod && phase !== 'active') {
         const isStopped = phase === 'declined' || phase === 'failed'
         return { deny: isStopped ? `${definition.name} is not set up. Its toast says why.` : `${definition.name} is installing. Try again when it's ready.` } as EventResult<N>
@@ -688,7 +704,7 @@ 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(definition.name, hook, listener, report))
+  const hookOn = <H extends Hook>(hook: H, listener: HookListener<H>): Disposable => router.add(`classic.${hook}`, classicHook(hook, listener, report))
   const expand = (path: string) => (homePrefix.test(path) ? resolvedPath(path, places) : path)
   const settingsFile = (source: 'user' | 'project' | 'local'): SettingsFile => ({
     read: () => checked.settings.read({ source }),
@@ -704,6 +720,7 @@ async function createMod<State extends object, Declared extends Options>(definit
     isGranted: (permission) => flag(permission),
     hookOn: (hook, listener) => hookOn(hook as Hook, listener as HookListener<Hook>),
     routeOn: (event, hook) => router.add(event, hook as never),
+    permissionRoutes: runtime.permissionRoutes,
   })
   let followed: Parameters<typeof client.follow>[0] | undefined
   let isSetUp = false
@@ -747,8 +764,8 @@ async function createMod<State extends object, Declared extends Options>(definit
         return hookOn('ConfigChange', async ({ source, file_path }) => {
           const change: SettingsFileChange = { source: source === 'skills' ? 'skills' : (source.replace('_settings', '') as SettingsFileChange['source']), ...(file_path === undefined ? {} : { path: file_path }) }
           if (matcher !== undefined && !matches(change, matcher)) return undefined
-          const answer = await listener(change)
-          return answer === undefined ? undefined : { decision: 'block', reason: answer.refuse }
+          const refuse = (await listener(change))?.refuse
+          return typeof refuse === 'string' ? { block: refuse } : undefined
         })
       },
     },
@@ -769,9 +786,10 @@ async function createMod<State extends object, Declared extends Options>(definit
         const watch = { paths, listener }
         watches.add(watch)
         if (watches.size === 1) {
-          hookOn('SessionStart', () => ({ hookSpecificOutput: { watchPaths: [...new Set([...watches].flatMap((each) => each.paths))] } }))
+          hookOn('SessionStart', () => ({ watchPaths: [...new Set([...watches].flatMap((each) => each.paths))] }))
           hookOn('FileChanged', ({ file_path, event }) => {
             for (const each of watches) if (each.paths.some((watched) => relativePath(watched, file_path) !== undefined)) void Promise.resolve(each.listener({ path: file_path, type: event })).catch((error: unknown) => report({ id: 'fs:onChange', message: 'The fs.onChange listener failed', error }))
+            return undefined
           })
         }
         return { dispose: () => void watches.delete(watch) }
@@ -955,7 +973,7 @@ async function createMod<State extends object, Declared extends Options>(definit
   await failsAs('its setup function threw', () => definition.setup(mod))
   isSetUp = true
   const permissionHooks = permissionEvents.filter((event) => router.has(event))
-  if (permissionHooks.length > 0 && !runtime.checksPermissions()) {
+  if (permissionHooks.length > 0 && runtime.permissionRoutes() === undefined) {
     throw new Error(`it decides permissions on ${listed(permissionHooks)}, so hooks/register.ts must call registerPermissionCheck(addHook) after registerMod`)
   }
   await failsAs('its open panes did not load', () => area.restorePanes())
@@ -965,7 +983,7 @@ async function createMod<State extends object, Declared extends Options>(definit
 function checkingKeys(claude: Claude, toast: Toast, keys: Readonly<Record<string, string>>): Claude {
   const bound = Object.entries(keys)
   if (bound.length === 0) return claude
-  const register: Claude['command']['register'] = (command) => {
+  const addCommand: Claude['command']['register'] = (command) => {
     for (const [key, commandName] of bound) {
       if (commandName === command.name && command.immediate !== true) {
         toast.warning(`${key} runs /${command.name}, which waits for Claude's turn to end`, { id: `key:${key}`, description: `It adds a row to the conversation. Give /${command.name} immediate: true.`, duration: Infinity })
@@ -973,7 +991,7 @@ function checkingKeys(claude: Claude, toast: Toast, keys: Readonly<Record<string
     }
     return claude.command.register(command)
   }
-  return { ...claude, command: { ...claude.command, register } }
+  return { ...claude, command: { ...claude.command, register: addCommand } }
 }
 
 const longestTimerMs = 2_147_483_647

package/src/runtime/permission-check.ts

@@ -0,0 +1,47 @@
+import type { Disposable } from '../mod.js'
+import type { HookFields } from './hooks.js'
+import { defined, processPayloadOf, recordOf, type HookOn, type RouteOn, type ToolCheck } from './sessions.js'
+
+export type PermissionUse = {
+  readonly raise: (method: string, payload: HookFields) => Promise<HookFields | undefined>
+  readonly hookOn: HookOn
+  readonly routeOn: RouteOn
+  readonly current: () => { readonly id: string; readonly cwd: string }
+}
+
+export type PermissionRoutes = (method: string, use: PermissionUse) => Disposable
+
+type Verdict = { readonly decision: 'allow' | 'ask' | 'deny'; readonly reason?: string; readonly rule?: string }
+
+const verdictName = (decision: Verdict['decision']) => (decision === 'deny' ? 'refuse' : decision)
+
+export const permissionRoutes: PermissionRoutes = (method, { raise, 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 { 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) }
+      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
+    })
+  }
+  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
+  })
+}

package/src/runtime/sessions.ts

@@ -12,12 +12,13 @@ import { GoalChange, type Goal } from '../session/goal/goal.js'
 import { TaskEnd, TaskStart, type Task } from '../session/goal/task.js'
 import { beforeEvents, processEvents, Session, sessionEvents, type BeforeEvent, type Placement, type BeforeMethods, type Surface, type OnMethods, type ProcessBeforeMethods, type ProcessName, type ProcessOnMethods, type RecordPart, type SearchOptions, type SessionEvent, type SessionScope, type SessionSend, type Sessions, type TaskOwner, type TaskStartArgs, type ToolCallArgs, type Usage } from '../session/session.js'
 import { matches, sentMatcher, type Matcher, type SentMatcher } from '../utils/matcher.js'
-import { foldAnswers, type Answers, type Place } from './before.js'
+import { beforeAnswerKeys, foldAnswers, foldBefore, methodOf, takenAnswer, type Answers, type Place } from './before.js'
 import type { Claude } from './claude.js'
 import { cmodPluginName } from './dependencies.js'
 import { messageOf } from '../utils/text.js'
 import { listenerOf, PassedTimeout, withinTime, type ListenOptions, type ListenTime } from './deadline.js'
-import { callFiles, type Hook, type HookAnswer } from './hooks.js'
+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 }
 
@@ -50,8 +51,6 @@ const ownSchedule: readonly string[] = ['CronDelete', 'CronList']
 
 export const beforePermission = (event: BeforeEvent): string => (event === 'toolCall' ? 'tools' : event === TaskStart ? 'tasks' : 'prompt')
 
-const methodOf = (prefix: 'on' | 'before', event: SessionEvent): string => `${prefix}${Object.entries(sessionEvents).find(([, each]) => each === event)?.[0] ?? event}`
-
 export const isAct = (action: string): action is Act => action === 'callTool' || action in actPermissions
 
 export function toolPermission(tool: string): string | undefined {
@@ -134,7 +133,9 @@ export function isInScope(scope: Scope, session: string, change: SessionChange,
   return (change.type === TurnStart || change.type === TurnEnd) && change.turn.prompt.id === scope.turn
 }
 
-export function createSessionsClient({ name, claude, report, isGranted, hookOn, routeOn }: { readonly name: string; readonly claude: Claude; readonly report: (id: string, message: string, error: unknown) => void; readonly isGranted: (permission: string) => boolean; readonly hookOn?: (hook: string, listener: (input: unknown) => unknown) => Disposable; readonly routeOn?: RouteOn }): SessionsClient {
+export type HookOn = (hook: string, listener: (input: unknown) => HookFields | undefined | Promise<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>
   const listening = new Map<string, Set<Listening>>()
   const deciding = new Map<string, Set<Listening>>()
@@ -197,6 +198,13 @@ export function createSessionsClient({ name, claude, report, isGranted, hookOn,
 
 
 
+  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
+    })
+
   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)
@@ -204,15 +212,11 @@ export function createSessionsClient({ name, claude, report, isGranted, hookOn,
         if (!isInScope(entry.scope, session, latest, isUnderIn(session))) return undefined
         if (entry.matcher !== undefined && !matches(payloadOf(latest), entry.matcher)) return undefined
         const payload = await payloadFor(session, latest)
-        const answer = await withinTime(claude.clock, entry.method, entry.options, (time) => entry.listener(payload as never, time)).catch((error: unknown) => {
-          if (entry.options.onFailure !== 'refuse') throw error
-          report(`session:${entry.method}`, `The ${entry.method} listener failed`, error)
-          return { refuse: `${name}: ${messageOf(error)}` }
-        })
+        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 foldAnswers(event, change, askers, (error) => report(`session:${methodOf('before', event)}`, `The ${methodOf('before', event)} listener failed`, error))
+    return foldBefore(event, change, askers, (error) => report(`session:${methodOf('before', event)}`, `The ${methodOf('before', event)} listener failed`, error))
   }
 
   const eventMethods = (scopeOf: () => Scope, hasBefore: boolean, ended?: string): OnMethods & Partial<BeforeMethods> => {
@@ -226,9 +230,11 @@ export function createSessionsClient({ name, claude, report, isGranted, hookOn,
     ]) as OnMethods & Partial<BeforeMethods>
   }
 
+  let folders: Promise<HomeFolders> | undefined
   const withFiles = async (message: Message): Promise<Message> => {
     if (message.type !== ToolCall && message.type !== ToolResult) return message
-    return { ...message, files: await callFiles(name, claude, { tool: message.name, input: message.input }, message.cwd) }
+    folders ??= Promise.all([claude.env.home(), claude.env.configHome()]).then(([home, configRoot]) => ({ home, configRoot }))
+    return { ...message, files: await callFiles(name, claude, folders, { tool: message.name, input: message.input }, message.cwd) }
   }
 
   const messagesFrom = async (method: string, input: unknown) => Promise.all((await call<Message[]>(method, input)).map(withFiles))
@@ -426,39 +432,17 @@ export function createSessionsClient({ name, claude, report, isGranted, hookOn,
   const processListeners = new Map<string, Set<ProcessListener>>()
 
   const raise = async (method: string, payload: HookFields): Promise<HookFields | undefined> => {
-    const isBefore = method.startsWith('before')
     const heard = [...(processListeners.get(method) ?? [])].filter(({ matcher }) => payload['task'] === undefined && (matcher === undefined || matches(payload, matcher)))
-    if (!isBefore) {
-      await Promise.all(
-        heard.map(({ listener, options }) =>
-          withinTime(claude.clock, method, options, (time) => listener(payload, time)).catch((error: unknown) => {
-            if (!(error instanceof PassedTimeout)) report(`session:${method}`, `The ${method} listener failed`, error)
-          }),
-        ),
-      )
+    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)] ?? []
-    let merged: HookFields | undefined
-    for (const { listener, options } of heard) {
-      try {
-        const answer = (await withinTime(claude.clock, method, options, (time) => listener(payload, time))) as HookFields | null | undefined
-        if (answer === undefined || answer === null) continue
-        const unread = Object.keys(answer).filter((key) => !takes.includes(key))
-        if (unread.length > 0) throw new Error(`it answered ${unread.join(' and ')}, which ${method} does not take. It takes ${takes.map((key) => `{ ${key} }`).join(', ') || 'no answer'}.`)
-        const notes = [merged?.['note'], answer['note']].filter((note): note is string => typeof note === 'string')
-        merged = { ...merged, ...answer, ...(notes.length === 0 ? {} : { note: notes.join('\n\n') }) }
-        if (typeof answer['refuse'] === 'string') return merged
-      } catch (error) {
-        report(`session:${method}`, `The ${method} listener failed`, error)
-        if (options.onFailure === 'refuse' || method === 'beforePermissionRequest') return { refuse: `${name}: ${messageOf(error)}` }
-      }
-    }
-    return merged
+    const askers = heard.map(({ listener, options }) => () => invoke(method, { ...options, ...failing }, 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 permissionCheck = (e: ToolCheck, below: ToolCheckVerdict): HookFields => ({ session: current.id, cwd: current.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 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) }
@@ -483,30 +467,21 @@ export function createSessionsClient({ name, claude, report, isGranted, hookOn,
   const listenTo = (method: string, named: string) => {
     if (hookOn === undefined || routeOn === undefined) throw new Error(`${name}: ${method} works only in a mod's own session.`)
     const isBefore = method.startsWith('before')
-    if (named === 'PermissionCheck') {
-      return routeOn('tool.check', async (e: ToolCheck, next) => {
-        const below = (await next(e)) as ToolCheckVerdict
-        if (!isBefore) {
-          void raise(method, permissionCheck(e, below))
-          return below
-        }
-        const answer = await raise(method, permissionCheck(e, below))
-        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
-      })
+    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)
     }
     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 Exclude<ProcessName, 'PermissionCheck'>, input)
+      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, hook, answer)
+      return answer === undefined ? undefined : hookAnswerOf(named, answer)
     })
   }
 
@@ -550,14 +525,14 @@ export function createSessionsClient({ name, claude, report, isGranted, hookOn,
     },
     changed(session, change, isInProject) {
       remember(session, change)
+      let payload: Promise<unknown> | undefined
       for (const key of isInProject ? [session, everySession] : [session]) {
         for (const { scope, event, method, matcher, listener, options } of listening.get(key) ?? []) {
           if (!isHeardBy(event, matcher, change) || !isInScope(scope, session, change, isUnderIn(session))) continue
-          void payloadFor(session, change)
-            .then((payload) => withinTime(claude.clock, method, options, (time) => listener(payload as never, time)))
-            .catch((error: unknown) => {
-              if (!(error instanceof PassedTimeout)) report(`session:${method}`, `The ${method} listener failed`, error)
-            })
+          payload ??= payloadFor(session, change)
+          void payload
+            .then((heard) => invoke(method, options, (time) => listener(heard as never, time)))
+            .catch((error: unknown) => report(`session:${method}`, `The ${method} listener failed`, error))
         }
       }
     },
@@ -583,22 +558,16 @@ export function createSessionsClient({ name, claude, report, isGranted, hookOn,
   }
 }
 
-type HookFields = Readonly<Record<string, unknown>>
-
-type ToolCheck = { readonly tool: string; readonly input: unknown; readonly tool_use_id?: string; readonly agentId?: string; readonly ceiling?: 'allow' | 'ask' | 'deny' }
-
-type ToolCheckVerdict = { readonly decision: 'allow' | 'ask' | 'deny'; readonly reason?: string; readonly rule?: string }
+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
 }
 
-const verdictName = (decision: 'allow' | 'ask' | 'deny') => (decision === 'deny' ? 'refuse' : decision)
+export const recordOf = (value: unknown): Readonly<Record<string, unknown>> => (typeof value === 'object' && value !== null && !Array.isArray(value) ? (value as Record<string, unknown>) : {})
 
-const recordOf = (value: unknown): Readonly<Record<string, unknown>> => (typeof value === 'object' && value !== null && !Array.isArray(value) ? (value as Record<string, unknown>) : {})
-
-const defined = (fields: HookFields): HookFields => Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined))
+export const defined = (fields: HookFields): HookFields => Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined))
 
 const placementOf = (input: HookFields): Placement => defined({ session: input['session_id'], task: input['agent_id'], agentType: input['agent_type'], cwd: input['cwd'], permissionMode: input['permission_mode'] }) as Placement
 
@@ -635,7 +604,9 @@ const answerKeys: Readonly<Record<string, readonly string[]>> = {
 
 const todoOf = (input: HookFields) => ({ id: input['task_id'], subject: input['task_subject'], description: input['task_description'], teammate: input['teammate_name'] })
 
-const processFields: { readonly [Name in Exclude<keyof typeof processEvents, 'PermissionCheck'>]: (input: HookFields) => HookFields } = {
+type ProcessFieldsName = Exclude<ProcessName, 'PermissionCheck'>
+
+const processFields: { readonly [Name in ProcessFieldsName]: (input: HookFields) => HookFields } = {
   ProjectSetup: (input) => ({ trigger: input['trigger'] }),
   SessionStart: (input) => ({
     source: input['source'],
@@ -683,28 +654,24 @@ export async function spawnTask(claude: Pick<Claude, 'agent'>, task: TaskStartAr
   return { id: started.agentId, title: task.title, agentType: task.agentType ?? 'general-purpose', model: started.model, openedBy: '', openedAt: new Date().toISOString() }
 }
 
-export function processPayloadOf(named: Exclude<keyof typeof processEvents, 'PermissionCheck'>, input: unknown): HookFields {
+export function processPayloadOf(named: ProcessFieldsName, input: unknown): HookFields {
   const fields = recordOf(input)
   return { ...placementOf(fields), ...defined(processFields[named](fields)) }
 }
 
-export function hookAnswerOf(named: string, hook: string, answer: HookFields): HookAnswer | undefined {
-  const output = (fields: HookFields): HookAnswer => ({ hookSpecificOutput: { hookEventName: hook as Hook, ...defined(fields) } })
+function hookAnswerOf(named: string, answer: HookFields): HookFields | undefined {
   const refuse = typeof answer['refuse'] === 'string' ? answer['refuse'] : undefined
-  if (named === 'SessionStart') return output({ additionalContext: answer['note'], sessionTitle: answer['title'], reloadSkills: answer['reloadSkills'], initialUserMessage: answer['firstPrompt'] })
+  const note = typeof answer['note'] === 'string' ? [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 output({ permissionDecision: 'deny', permissionDecisionReason: refuse })
-    return typeof answer['ask'] === 'string' ? output({ permissionDecision: 'ask', permissionDecisionReason: answer['ask'] }) : undefined
-  }
-  if (named === 'WorktreeCreate') return output({ worktreePath: answer['result'] })
-  if (named === 'PermissionRequest') {
-    if (refuse !== undefined) return output({ decision: defined({ behavior: 'deny', message: refuse, interrupt: answer['interrupt'] }) })
-    return answer['allow'] === true ? output({ decision: defined({ behavior: 'allow', updatedInput: answer['input'], updatedPermissions: answer['updates'] }) }) : undefined
+    if (refuse !== undefined) return { permissionDecision: 'deny', permissionDecisionReason: refuse }
+    return typeof answer['ask'] === 'string' ? { permissionDecision: 'ask', permissionDecisionReason: answer['ask'] } : undefined
   }
-  if (named === 'PermissionDenial') return output({ retry: answer['retry'] })
-  if (named === 'ToolBatch') return output({ additionalContext: answer['note'] })
-  if (named === 'ReplyDisplay') return output({ displayContent: answer['text'] })
-  return refuse === undefined ? undefined : { decision: 'block', reason: refuse }
+  if (named === 'WorktreeCreate') return defined({ worktreePath: answer['result'] })
+  if (named === 'PermissionDenial') return answer['retry'] === true ? { retry: true } : undefined
+  if (named === 'ToolBatch') return defined({ additionalContext: note })
+  if (named === 'ReplyDisplay') return defined({ displayContent: answer['text'] })
+  return refuse === undefined ? undefined : { block: refuse }
 }
 
 export function resultOf(where: Pick<Place, 'session' | 'context' | 'turn'>, call: ToolCallArgs & { readonly cwd: string }, answered: Awaited<ReturnType<Claude['tool']['call']>>): ToolResult {

package/src/runtime/state.ts

@@ -84,14 +84,19 @@ export function createState<State extends object>({ name, initial, session, root
 
   const forgetEndedSessions = async (current: string) => {
     const stored = await claude.store.keys()
-    for (const recorded of stored.filter((key) => key.startsWith(transcriptsKey))) {
-      const owner = recorded.slice(transcriptsKey.length)
-      if (owner === current) continue
+    const ended = async (recorded: string) => {
       const transcript = await claude.store.get(recorded)
-      if (typeof transcript === 'string' && (await claude.fs.exists(transcript))) continue
-      for (const value of stored.filter((key) => key.startsWith(`${name}.`) && key.endsWith(`.sessions.${owner}`))) await claude.store.delete(value)
-      await claude.store.delete(recorded)
+      return typeof transcript !== 'string' || !(await claude.fs.exists(transcript))
     }
+    const owners = stored.filter((key) => key.startsWith(transcriptsKey) && key !== `${transcriptsKey}${current}`)
+    await Promise.all(
+      owners.map(async (recorded) => {
+        if (!(await ended(recorded))) return
+        const owner = recorded.slice(transcriptsKey.length)
+        await Promise.all(stored.filter((key) => key.startsWith(`${name}.`) && key.endsWith(`.sessions.${owner}`)).map((value) => claude.store.delete(value)))
+        await claude.store.delete(recorded)
+      }),
+    )
   }
 
   const loadGroups = async (only: readonly Lifetime[], next: { readonly root: string; readonly session: string }) => {
@@ -151,8 +156,10 @@ export function createState<State extends object>({ name, initial, session, root
     moveTo: (nextRoot) => inTurn(async () => (nextRoot === projectRoot ? undefined : loadGroups(['project'], { root: nextRoot, session: sessionId }))),
     switchSession: (nextSession, source, transcript) =>
       inTurn(async () => {
-        await claude.store.set(`${transcriptsKey}${nextSession}`, transcript)
-        await forgetEndedSessions(nextSession)
+        if (Object.keys(declared.session).length > 0) {
+          await claude.store.set(`${transcriptsKey}${nextSession}`, transcript)
+          void forgetEndedSessions(nextSession).catch((error: unknown) => report({ id: 'state:sessions', message: 'Could not forget the session values of ended sessions', error }))
+        }
         if (nextSession === sessionId) return
         if (source === 'fork') await copySession(sessionId, nextSession)
         return loadGroups(['memory', 'session'], { root: projectRoot, session: nextSession })

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

@@ -50,7 +50,11 @@ export const skillPrefix = 'Base directory for this skill:'
 
 const rowTypes: readonly string[] = ['user', 'assistant', 'attachment', 'system']
 
-const memoryPath = /^Contents of (.+?) \(/
+const memoryPath = /^Contents of (.+?)(?: \([^)\n]*\))?:\r?$/m
+
+export function instructionPathOf(text: string): string {
+  return memoryPath.exec(text)?.[1] ?? ''
+}
 
 export function rowOfLine(row: Readonly<Record<string, unknown>>): Row | undefined {
   const { uuid, timestamp, type } = row
@@ -77,7 +81,7 @@ export function rowOfLine(row: Readonly<Record<string, unknown>>): Row | undefin
 export function rowOfAppend(append: { readonly uuid: string; readonly door: string; readonly origin: unknown; readonly message: { readonly type: Row['type']; readonly name?: string; readonly isMeta?: true; readonly content: readonly unknown[] } }, at: string, cwd: string): Row {
   const { message, origin } = append
   const text = textOf(message.content)
-  const path = message.type === 'attachment' ? memoryPath.exec(text)?.[1] : undefined
+  const path = message.type === 'attachment' ? instructionPathOf(text) || undefined : undefined
   const model = isObject(origin) && origin['kind'] === 'model' && typeof origin['model'] === 'string' ? origin['model'] : undefined
   return {
     id: append.uuid,

package/src/testing.ts

@@ -23,7 +23,8 @@ import type { Options, OptionValues } from './options.js'
 import { readSteps, storeFolder, type Steps } from './records.js'
 import type { Claude } from './runtime/claude.js'
 import { answerCall, cmodPluginName, notInstalled } from './runtime/dependencies.js'
-import { foldAnswers, installBefore } from './runtime/before.js'
+import { foldBefore, installBefore } from './runtime/before.js'
+import { permissionRoutes } from './runtime/permission-check.js'
 import type { RoutedEvent } from './runtime/hooks.js'
 import { keepClaudeCode, type ClaudeCode } from './testing/claude-code.js'
 import { createRouter } from './runtime/router.js'
@@ -174,7 +175,7 @@ export function testMod<State extends object, Declared extends Options = Options
   const starting = options.state as Record<string, object> | undefined
   const declared = Object.entries(definition.state ?? {}) as [string, object][]
   const state = Object.fromEntries(declared.map(([lifetime, values]) => [lifetime, { ...values, ...starting?.[lifetime] }])) as State
-  const lifecycle = createLifecycle<State, Declared>({ ...definition, state }, () => true, (options.options ?? {}) as PluginOptions, false)
+  const lifecycle = createLifecycle<State, Declared>({ ...definition, state }, () => permissionRoutes,(options.options ?? {}) as PluginOptions, false)
   let started: Promise<void> | undefined
 
   const start = async () => {
@@ -212,7 +213,7 @@ export function testMod<State extends object, Declared extends Options = Options
     hooks: {
       place: async () => conversations.place(),
       wants: async (event) => conversations.wants(name, event),
-      decide: (event, change) => foldAnswers(event, change, [(latest) => askMod(event, latest)], (error) => fake.claude.ui.log(`cmod: passed the ${event} on without ${name}'s answer: ${messageOf(error)}`, { to: 'debug' })),
+      decide: (event, change) => foldBefore(event, change, [(latest) => askMod(event, latest)], (error) => fake.claude.ui.log(`cmod: passed the ${event} on without ${name}'s answer: ${messageOf(error)}`, { to: 'debug' })),
     },
   })