@cmodjs/core 3.0.0 → 4.0.0

package/src/runtime/options.ts

@@ -1,6 +1,6 @@
 import type { PluginOptions } from 'claude-code'
 import { fitsOption, isUnset, type Option, type Options } from '../options.js'
-import { configFolders } from '../records.js'
+import { configFolders, secretFix } from '../records.js'
 import { listed, messageOf } from '../utils/text.js'
 import type { Claude } from './claude.js'
 import type { Failure } from './toaster.js'
@@ -72,7 +72,7 @@ export function createOptions({
     for (const [key, value] of Object.entries(file)) {
       const option = declared[key]
       if (option === undefined) ignore(`sets ${key}, which ${name} does not declare. ${Object.keys(declared).length === 0 ? 'Remove it.' : `Remove it, or use one of: ${Object.keys(declared).join(', ')}.`}`)
-      else if (option.type === 'secret') ignore(`sets ${key}, a secret, and a project file is committed for everyone to read. Remove it, and set it in /config.`)
+      else if (option.type === 'secret') ignore(`sets ${key}, a secret, and a project file is committed for everyone to read. Remove it. ${secretFix}`)
       else {
         const misfit = fitsOption(option, value)
         if (misfit === undefined) kept[key] = value

package/src/runtime/pages.ts

@@ -0,0 +1,127 @@
+import type { RenderElement } from 'claude-code'
+import { isObject } from '../records.js'
+import { messageOf } from '../utils/text.js'
+import type { Claude } from './claude.js'
+import type { DrawnParts } from './parts.js'
+import type { Router } from './router.js'
+import { partMethods, type PageDeclaration, type PageRequest, type PartPress, type PartsUpdate, type ShownPages } from './ui.js'
+import type { Widgets } from './widgets.js'
+
+const askedWaitMs = 1000
+
+export type ModPages = { readonly mod: string; readonly pages: readonly PageDeclaration[] }
+
+export type PageApply = (mod: string, requests: readonly PageRequest[]) => Promise<void>
+
+export type Pages = {
+  declared(): readonly ModPages[]
+  element(mod: string, page: string, params: unknown, columns: number, isFocused: boolean): RenderElement | undefined
+  press(mod: string, press: PartPress): void
+  update(mod: string, update: PartsUpdate): boolean
+  tell(mod: string, shown: ShownPages): void
+  apply(listener: PageApply): void
+}
+
+export function pagesOf(input: unknown): PageDeclaration[] {
+  const listed = isObject(input) && Array.isArray(input['pages']) ? (input['pages'] as unknown[]) : []
+  return listed.filter(isObject).flatMap((each) => (typeof each['id'] === 'string' && typeof each['title'] === 'string' && (each['place'] === 'sidebar' || each['place'] === 'settings') ? [{ id: each['id'], title: each['title'], place: each['place'] }] : []))
+}
+
+export function servePages({ claude, router, report, widgets, parts }: { readonly claude: Claude; readonly router: Router; readonly report: (id: string, message: string, error: unknown) => void; readonly widgets: Pick<Widgets, 'update'>; readonly parts: DrawnParts }): Pages {
+  const declared = new Map<string, readonly PageDeclaration[]>()
+  const asking = new Map<string, Promise<void>>()
+  const pressing = new Set<Promise<void>>()
+  let waiting: { readonly mod: string; readonly requests: readonly PageRequest[] }[] = []
+  let inputDepth = 0
+  let applyTo: PageApply = async () => undefined
+
+  const run = (mod: string, requests: readonly PageRequest[]) =>
+    applyTo(mod, requests).catch((error: unknown) => report(`pages:${mod}`, `Could not show the page ${mod} asked for`, error))
+
+  const takeWaiting = async () => {
+    const taken = waiting
+    waiting = []
+    for (const { mod, requests } of taken) await run(mod, requests)
+  }
+
+  const settle = async () => {
+    while (pressing.size > 0) await Promise.allSettled(pressing)
+    await takeWaiting()
+  }
+
+  const wrapped = async <Answer>(next: () => Promise<Answer>): Promise<Answer> => {
+    inputDepth += 1
+    try {
+      const answer = await next()
+      await settle()
+      return answer
+    } finally {
+      inputDepth -= 1
+    }
+  }
+
+  router.add('command.run', (e, next) => wrapped(async () => (waiting.length > 0 ? {} : next(e))))
+  router.add('ui.press', (e, next) => wrapped(() => next(e)))
+
+  const ask = (mod: string) => {
+    const pending =
+      asking.get(mod) ??
+      claude.cmod
+        .call({ to: mod, method: partMethods.list, input: null })
+        .then(
+          (parts) => void declared.set(mod, pagesOf(parts)),
+          (error: unknown) => claude.ui.log(`cmod: ${mod} did not list its pages: ${messageOf(error)}`, { to: 'debug' }),
+        )
+        .finally(() => asking.delete(mod))
+    asking.set(mod, pending)
+    return pending
+  }
+
+  const update = (mod: string, { parts: listing, redraw, requests, isAsked }: PartsUpdate) => {
+    if (listing !== undefined) declared.set(mod, pagesOf(listing))
+    if (listing !== undefined || redraw === true) widgets.update(mod, { ...(listing === undefined ? {} : { parts: listing }), ...(redraw === undefined ? {} : { redraw }) })
+    if (requests === undefined || requests.length === 0) return false
+    if (isAsked !== true) return (void run(mod, requests), false)
+    waiting.push({ mod, requests })
+    if (inputDepth > 0) return true
+    claude.clock.after(askedWaitMs, () => void takeWaiting())
+    return false
+  }
+
+  const press = (mod: string, input: PartPress) => {
+    const pending = claude.cmod
+      .call({ to: mod, method: partMethods.press, input })
+      .then(
+        (answer) => void update(mod, (isObject(answer) ? answer : {}) as PartsUpdate),
+        (error: unknown) => {
+          parts.forget(mod)
+          claude.ui.invalidate('ui.render')
+          report(`press:${mod}`, `${mod} did not take the press`, error)
+        },
+      )
+      .finally(() => pressing.delete(pending))
+    pressing.add(pending)
+    if (inputDepth === 0) void pending.then(takeWaiting)
+  }
+
+  const cacheKey = (page: string, params: unknown, columns: number, isFocused: boolean) => `${page}\u0000${JSON.stringify(params ?? null)}\u0000${columns}\u0000${isFocused}`
+
+  return {
+    declared: () => [...declared].map(([mod, pages]) => ({ mod, pages })),
+    element(mod, page, params, columns, isFocused) {
+      if (!declared.has(mod)) void ask(mod)
+      const cached = cacheKey(page, params, columns, isFocused)
+      const name = `The ${page} page of ${mod}`
+      void parts.fill(mod, cached, { page, params: params ?? null, columns, isFocused }, name)?.then(() => claude.ui.invalidate('ui.render'))
+      return parts.element(mod, cached, `${mod}/${page}:`, name, `page:${mod}/${page}`)
+    },
+    press,
+    update,
+    tell(mod, shown) {
+      void claude.cmod.call({ to: mod, method: partMethods.shown, input: shown }).catch((error: unknown) => claude.ui.log(`cmod: ${mod} did not hear which of its pages show: ${messageOf(error)}`, { to: 'debug' }))
+    },
+    apply(listener) {
+      applyTo = listener
+    },
+  }
+}

package/src/runtime/parts.ts

@@ -0,0 +1,72 @@
+import type { RenderElement } from 'claude-code'
+import { elementOf } from '../ui/elements.js'
+import { messageOf } from '../utils/text.js'
+import type { Claude } from './claude.js'
+import { partMethods, type DrawnPart, type PartPress } from './ui.js'
+
+export type DrawnParts = {
+  fill(mod: string, cached: string, input: Readonly<Record<string, unknown>>, name: string): Promise<void> | undefined
+  element(mod: string, cached: string, keyPrefix: string, name: string, reportId: string): RenderElement | undefined
+  forget(mod: string): void
+}
+
+type Drawn = { readonly data: DrawnPart | null; readonly generation: number }
+
+const keptDrawings = 200
+
+export function drawnParts({ claude, report, press }: { readonly claude: Claude; readonly report: (id: string, message: string, error: unknown) => void; readonly press: (mod: string, press: PartPress) => void }): DrawnParts {
+  const drawn = new Map<string, Drawn>()
+  const drawing = new Map<string, Promise<void>>()
+  const generations = new Map<string, number>()
+  const keyOf = (mod: string, cached: string) => `${mod}\u0000${cached}`
+  const generationOf = (mod: string) => generations.get(mod) ?? 0
+
+  return {
+    fill(mod, cached, input, name) {
+      const key = keyOf(mod, cached)
+      const generation = generationOf(mod)
+      if (drawn.get(key)?.generation === generation) return undefined
+      const keep = (data: DrawnPart | null) => {
+        drawn.delete(key)
+        drawn.set(key, { data, generation })
+        const [oldest] = drawn.keys()
+        if (drawn.size > keptDrawings && oldest !== undefined) drawn.delete(oldest)
+        if (generationOf(mod) !== generation) claude.ui.invalidate('ui.render')
+      }
+      const pending =
+        drawing.get(key) ??
+        claude.cmod
+          .call({ to: mod, method: partMethods.draw, input })
+          .then(
+            (data) => keep((data ?? null) as DrawnPart | null),
+            (error: unknown) => {
+              claude.ui.log(`cmod: ${name} drew nothing: ${messageOf(error)}`, { to: 'debug' })
+              keep(null)
+            },
+          )
+          .finally(() => drawing.delete(key))
+      drawing.set(key, pending)
+      return pending
+    },
+    element(mod, cached, keyPrefix, name, reportId) {
+      const key = keyOf(mod, cached)
+      const entry = drawn.get(key)
+      if (entry === undefined) return undefined
+      drawn.delete(key)
+      drawn.set(key, entry)
+      const { data } = entry
+      if (data === null || data.tree === null) return undefined
+      try {
+        return elementOf(data.tree, keyPrefix, (handler, args) => press(mod, { draw: data.draw, handler, args })) as RenderElement
+      } catch (error) {
+        report(reportId, `${name} could not draw`, error)
+        return undefined
+      }
+    },
+    forget(mod) {
+      const superseded = generationOf(mod)
+      generations.set(mod, superseded + 1)
+      for (const [key, { generation }] of drawn) if (key.startsWith(`${mod}\u0000`) && generation < superseded) drawn.delete(key)
+    },
+  }
+}

package/src/runtime/permission-check.ts

@@ -1,4 +1,4 @@
-import type { Disposable } from '../mod.js'
+import type { Subscription } from '../utils/subscription.js'
 import type { HookFields } from './hooks.js'
 import { defined, processPayloadOf, recordOf, type HookOn, type RouteOn, type ToolCheck } from './sessions.js'
 
@@ -10,12 +10,14 @@ export type PermissionUse = {
   readonly current: () => { readonly id: string; readonly cwd: string }
 }
 
-export type PermissionRoutes = (method: string, use: PermissionUse) => Disposable
+export type PermissionRoutes = (method: string, use: PermissionUse) => Subscription
 
 type Verdict = { readonly decision: 'allow' | 'ask' | 'deny'; readonly reason?: string; readonly rule?: string }
 
 const verdictName = (decision: Verdict['decision']) => (decision === 'deny' ? 'refuse' : decision)
 
+type BuildFlags = { readonly cmodWithoutApprove?: true }
+
 export const permissionRoutes: PermissionRoutes = (method, { raise, refusalFor, hookOn, routeOn, current }) => {
   const isBefore = method.startsWith('before')
   if (method.endsWith('PermissionCheck')) {
@@ -39,8 +41,11 @@ export const permissionRoutes: PermissionRoutes = (method, { raise, refusalFor,
         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
+        if (!(globalThis as BuildFlags).cmodWithoutApprove) {
+          if (typeof answer['ask'] === 'string') return { decision: 'ask', reason: answer['ask'] }
+          if (answer['allow'] === true) return { decision: 'allow' }
+        }
+        return below
       },
       isBefore ? failed : undefined,
     )
@@ -57,7 +62,10 @@ export const permissionRoutes: PermissionRoutes = (method, { raise, refusalFor,
       const answer = await raise(method, payload)
       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
+      if (!(globalThis as BuildFlags).cmodWithoutApprove) {
+        if (answer['allow'] === true) return { decision: defined({ behavior: 'allow', updatedInput: answer['input'], updatedPermissions: answer['updates'] }) }
+      }
+      return undefined
     },
     isBefore
       ? (input, error) => {

package/src/runtime/programs.ts

@@ -47,7 +47,7 @@ export function locatingPrograms(claude: Claude): Programs {
   let names: ReadonlySet<string> = new Set()
   const located = (argv: readonly string[]): readonly string[] => {
     const [name, ...rest] = argv
-    return folder !== undefined && name !== undefined && names.has(name) ? [`${folder}/${name}`, ...rest] : argv
+    return folder !== undefined && name !== undefined && (name === 'cmod' || names.has(name)) ? [`${folder}/${name}`, ...rest] : argv
   }
   return {
     claude: {

package/src/runtime/router.ts

@@ -1,5 +1,5 @@
 import type { Args, EventResult, Frozen } from 'claude-code'
-import type { Disposable } from '../mod.js'
+import type { Subscription } from '../utils/subscription.js'
 import type { RoutedEvent } from './hooks.js'
 
 export type RouterNext<N extends RoutedEvent> = (e: Frozen<Args<N>>) => Promise<EventResult<N>>
@@ -9,7 +9,7 @@ export type RoutedHook<N extends RoutedEvent> = (e: Frozen<Args<N>>, next: Route
 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>, failed?: RoutedFailure<N>): Disposable
+  add<N extends RoutedEvent>(event: N, hook: RoutedHook<N>, failed?: RoutedFailure<N>): Subscription
   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>>
 }
@@ -24,7 +24,7 @@ export function createRouter(): Router {
       const route = { hook, ...(failed === undefined ? {} : { failed }) } as Route
       routes.set(event, [...(routes.get(event) ?? []), route])
       return {
-        dispose() {
+        remove() {
           const chain = (routes.get(event) ?? []).filter((each) => each !== route)
           if (chain.length === 0) routes.delete(event)
           else routes.set(event, chain)

package/src/runtime/sessions.ts

@@ -1,5 +1,5 @@
 import type { Args, CommandRunResult, SessionCompactResult } from 'claude-code'
-import type { Disposable } from '../mod.js'
+import type { Subscription } from '../utils/subscription.js'
 import { ContextEnd, ContextStart, type Context } from '../session/context/context.js'
 import { Message, noFiles } from '../session/context/turn/message/message.js'
 import { modNote, Note } from '../session/context/turn/message/note.js'
@@ -16,11 +16,12 @@ import { beforeAnswerKeys, foldAnswers, foldBefore, methodOf, takenAnswer, type
 import type { Claude } from './claude.js'
 import { cmodPluginName } from './dependencies.js'
 import { messageOf } from '../utils/text.js'
+import { grantFix, permissionWords } from '../records.js'
 import { listenerOf, PassedTimeout, withinTime, type ListenOptions, type ListenTime } from './deadline.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; readonly onFailure?: 'refuse'; readonly scope?: Scope }
+export type Listened = { readonly event: SessionEvent; readonly matcher: SentMatcher | undefined; readonly onFailure?: 'refuse'; readonly scope?: Scope }
 
 export const everySession = '*'
 
@@ -33,7 +34,6 @@ export const conversationMethods = {
   tasks: 'cmod:tasks',
   goal: 'cmod:goal',
   updateGoal: 'cmod:updateGoal',
-  usage: 'cmod:usage',
   subscribe: 'cmod:subscribe',
   watchBefore: 'cmod:watchBefore',
   act: 'cmod:act',
@@ -69,7 +69,8 @@ export type SessionsClient = {
   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
+  listen(method: string, args: readonly unknown[]): Subscription
+  turn(data: TurnData): Turn
   /** An empty title keeps the title the session already has. */
   follow(current: Omit<SessionData, 'isRunning' | 'lastAt'>): void
 }
@@ -138,7 +139,7 @@ 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 type HookOn = (hook: string, listener: (input: unknown) => HookFields | undefined | Promise<HookFields | undefined>, failed?: (input: unknown, error: Error) => HookFields | undefined) => Subscription
 
 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>
@@ -156,7 +157,7 @@ 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[] =>
+      const heard = (from: Map<string, Set<Listening>>): Listened[] =>
         [...(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 }] : [])]
@@ -182,7 +183,7 @@ export function createSessionsClient({ name, claude, report, isGranted, hookOn,
     if (change.type === TaskStart) parents.get(session)?.set(change.task.id, change.task.parent)
   }
 
-  const add = (into: Map<string, Set<Listening>>, scope: Scope, event: SessionEvent, method: string, args: readonly unknown[], onChange: (key: string) => void): Disposable => {
+  const add = (into: Map<string, Set<Listening>>, scope: Scope, event: SessionEvent, method: string, args: readonly unknown[], onChange: (key: string) => void): Subscription => {
     const key = keyOf(scope)
     const entry: Listening = { scope, event, method, ...listenerOf(name, method, args) }
     const set = into.get(key) ?? new Set()
@@ -191,7 +192,7 @@ export function createSessionsClient({ name, claude, report, isGranted, hookOn,
     if (scope.task !== undefined || scope.isGoal === true) void learnTasks(scope.session ?? current.id).catch((error: unknown) => report(`tasks:${key}`, 'Could not read the tasks it listens under', error))
     onChange(key)
     return {
-      dispose() {
+      remove() {
         for (const [at, held] of into) {
           if (!held.delete(entry)) continue
           if (held.size === 0) into.delete(at)
@@ -224,7 +225,7 @@ export function createSessionsClient({ name, claude, report, isGranted, hookOn,
         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.`)
+        throw new Error(`Its ${entry.method} answer changes nothing until you grant ${name} "${permissionWords(beforePermission(event))}". ${grantFix}`)
       })
     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) }
@@ -534,7 +535,7 @@ export function createSessionsClient({ name, claude, report, isGranted, hookOn,
     return { ...compacted, messages: [...compacted.messages, { role: 'user', text: modNote(name, note), toolUses: [] }] }
   }
 
-  const listen = (method: string, args: readonly unknown[], isEveryAgent = false): Disposable => {
+  const listen = (method: string, args: readonly unknown[], isEveryAgent = false): Subscription => {
     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()
@@ -543,7 +544,7 @@ export function createSessionsClient({ name, claude, report, isGranted, hookOn,
       processListeners.set(method, held)
     }
     held.add(entry)
-    return { dispose: () => void held.delete(entry) }
+    return { remove: () => void held.delete(entry) }
   }
 
   const processMethods = (): ProcessOnMethods & ProcessBeforeMethods =>
@@ -552,7 +553,14 @@ export function createSessionsClient({ name, claude, report, isGranted, hookOn,
     ) as ProcessOnMethods & ProcessBeforeMethods
 
   const here = sessionOf(() => current)
-  const currentSession = Object.assign(here, processMethods(), { goal: Object.assign(here.goal, { beforeSessionStart: (...args: unknown[]) => listen('beforeSessionStart', args, true) }) })
+  const currentSession = Object.assign(here, processMethods(), {
+    goal: Object.assign(here.goal, { beforeSessionStart: (...args: unknown[]) => listen('beforeSessionStart', args, true) }),
+    async scrollTo(message: Message, options?: { readonly block?: 'start' | 'center' | 'end' | 'nearest' }) {
+      const { deny } = await claude.ui.scroll({ to: { requestId: message.id }, ...(options?.block === undefined ? {} : { block: options.block }) })
+      if (deny !== undefined) throw new Error(`${name}: Claude Code did not scroll to the message: ${deny}`)
+    },
+    caption: (toolCall: Message & { readonly type: typeof ToolCall }, text: string | undefined) => claude.ui.notice(toolCall.callId, text),
+  })
   const every = eventMethods(() => ({}), false)
 
   const answerBefore = async (session: string, event: BeforeEvent, change: SessionChange, isInProject: boolean) => (mayDecide(session) ? combined(session, event, change, isInProject) : undefined)
@@ -596,6 +604,7 @@ export function createSessionsClient({ name, claude, report, isGranted, hookOn,
     failedBefore,
     raise,
     listen,
+    turn: (data) => turnOf({ session: current.id }, data),
     follow(next) {
       const moved = next.id !== current.id && current.id !== ''
       const previous = current.id
@@ -618,9 +627,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>, 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
+  (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>): Subscription
+  (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>): Subscription
+  (event: 'session.compact', hook: (e: Args<'session.compact'>, next: (e: Args<'session.compact'>) => Promise<SessionCompactResult>) => Promise<SessionCompactResult>): Subscription
 }
 
 export const recordOf = (value: unknown): Readonly<Record<string, unknown>> => (typeof value === 'object' && value !== null && !Array.isArray(value) ? (value as Record<string, unknown>) : {})

package/src/runtime/state.ts

@@ -1,4 +1,5 @@
 import type { ClassicHookInputs } from 'claude-code'
+import type { Subscription } from '../utils/subscription.js'
 import type { Claude } from './claude.js'
 import type { Failure } from './toaster.js'
 
@@ -34,10 +35,11 @@ const keptProjects = 20
 
 const listeners = new WeakMap<object, Set<() => void>>()
 
-export function onStateChange(state: object, listener: () => void): void {
+export function onStateChange(state: object, listener: () => void): Subscription {
   const own = listeners.get(state) ?? new Set()
   own.add(listener)
   listeners.set(state, own)
+  return { remove: () => void own.delete(listener) }
 }
 
 export async function sessionsWith(claude: Pick<Claude, 'store'>, name: string, key: string, value: unknown): Promise<string[]> {

package/src/runtime/toaster.ts

@@ -1,7 +1,7 @@
 import type { ElementTable, RenderElement, RenderPropsOf, Timer } from 'claude-code'
 import type { Toast, ToastId, ToastOptions, ToastType } from '../mod.js'
 import { Box, Button, drawWith, Link, Text } from '../ui/elements.js'
-import { coreVersion, isObject } from '../records.js'
+import { coreVersion, grantFix, installFix, isObject, secretFix } from '../records.js'
 import { firstLine, messageOf } from '../utils/text.js'
 import type { Claude } from './claude.js'
 
@@ -54,7 +54,7 @@ const icons: Record<Exclude<ToastType, 'loading'>, { readonly glyph: string; rea
   error: { glyph: '✗', color: 'error' },
 }
 
-export function createToaster(claude: Claude, name: string, version: () => string | undefined): Toaster {
+export function createToaster(claude: Claude, name: string, version: () => string | undefined, openPermissions: () => unknown): Toaster {
   const entries = new Map<ToastId, Entry>()
   const hidden = new Map<string, string>()
   void claude.store.get(hiddenKey).then(
@@ -176,7 +176,7 @@ export function createToaster(claude: Claude, name: string, version: () => strin
       .then(run)
       .catch((error: unknown) => fail({ id: `press:${entry.id}`, message: `${entry.message}: the press failed`, error }))
 
-  const fail = ({ id, message, error, description = error === undefined ? undefined : describe(error), retry }: Failure): ToastId => {
+  const fail = ({ id, message, error, description = error === undefined || describe(error) === message ? undefined : describe(error), retry }: Failure): ToastId => {
     const hides = `${version() ?? ''}\n${message}\n${error === undefined ? '' : describe(error)}`
     if (hidden.get(id) === hides) return id
     hidden.delete(id)
@@ -214,7 +214,13 @@ export function createToaster(claude: Claude, name: string, version: () => strin
         }
       }
     }
-    const actions = [...(retry === undefined ? [] : [{ label: 'Retry', onClick: tryAgain }]), { label: 'Report', onClick: startReporting }]
+    const text = `${message}\n${description ?? ''}`
+    const fixes = [
+      { sentence: grantFix, label: 'Settings', onClick: openPermissions },
+      { sentence: installFix, label: 'Plugins', onClick: () => claude.command.run({ command: 'plugin' }) },
+      { sentence: secretFix, label: 'Open /config', onClick: () => claude.command.run({ command: 'config' }) },
+    ].filter(({ sentence }) => text.includes(sentence))
+    const actions = [...fixes, ...(retry === undefined ? [] : [{ label: 'Retry', onClick: tryAgain }]), { label: 'Report', onClick: startReporting }]
     return put('error', message, { id, ...(description === undefined ? {} : { description }), duration: Infinity }, actions, hides)
   }