@cmodjs/core 0.3.0 → 1.5.0

package/src/runtime/grants.ts

@@ -1,7 +1,9 @@
-import { permissionWords } from '../records.js'
+import { isObject, permissionWords } from '../records.js'
 import { relativePath } from '../utils/paths.js'
 import type { Claude } from './claude.js'
+import { cmodPluginName } from './dependencies.js'
 import type { RoutedEvent } from './hooks.js'
+import { actPermission, conversationMethods, isAct, toolPermission } from './sessions.js'
 
 export type Grants = {
   readonly name: string
@@ -12,24 +14,47 @@ export type Grants = {
   readonly configRoot: string | undefined
   readonly projectRoot: () => string
   readonly freeFolders: () => readonly string[]
+  readonly freeAddresses: () => ReadonlySet<string>
 }
 
 export class PermissionRefused extends Error {}
 
-const configFiles: readonly string[] = ['.claude/settings.json', '.claude/settings.local.json', '.mcp.json']
+const addressesOfPrograms = new WeakMap<object, Set<string>>()
 
-const startsTurns: readonly string[] = ['CronCreate']
+export function programAddresses(mod: object): Set<string> {
+  const known = addressesOfPrograms.get(mod) ?? new Set<string>()
+  addressesOfPrograms.set(mod, known)
+  return known
+}
 
-const ownSchedule: readonly string[] = ['CronDelete', 'CronList']
+const projectSettingsFiles: readonly string[] = ['.claude/settings.json', '.claude/settings.local.json', '.mcp.json']
+
+const conversationCalls: Readonly<Record<string, string>> = {
+  [conversationMethods.sessions]: 'sessions.list',
+  [conversationMethods.search]: 'sessions.search',
+  [conversationMethods.messages]: 'messages',
+  [conversationMethods.turns]: 'turns',
+  [conversationMethods.contexts]: 'contexts',
+  [conversationMethods.tasks]: 'tasks',
+  [conversationMethods.goal]: 'goal',
+  [conversationMethods.updateGoal]: 'goal.update',
+  [conversationMethods.subscribe]: 'on',
+  [conversationMethods.watchBefore]: 'before',
+  [conversationMethods.act]: 'act',
+}
 
-async function checkGrant(grants: Grants, call: string, item: string | undefined): Promise<void> {
+export async function checkGrant(grants: Grants, call: string, item: string | undefined): Promise<void> {
   if (item === undefined) return
   await grants.refresh()
   if (!isCovered(grants.granted(), item, grants.home)) throw new PermissionRefused(refusal(grants, call, item))
 }
 
-export function checkWrite(grants: Grants, call: string, path: string): Promise<void> {
-  return checkGrant(grants, call, writeItem(grants, path))
+export async function checkWrite(grants: Grants, call: string, path: string): Promise<void> {
+  await checkGrant(grants, call, writeItem(grants, path))
+}
+
+export async function checkSettings(grants: Grants, source: 'user' | 'project' | 'local', keys: readonly string[]): Promise<void> {
+  for (const key of keys) await checkGrant(grants, `settings.${source}.update(${key})`, `config:${key}`)
 }
 
 export function checkingGrants(claude: Claude, grants: Grants): Claude {
@@ -59,7 +84,7 @@ export function checkingGrants(claude: Claude, grants: Grants): Claude {
     },
     http: {
       async fetch(url, init) {
-        await gate(`http.fetch(${url})`, `network:${init?.socketPath ?? hostOf(url)}`)
+        if (!grants.freeAddresses().has(init?.socketPath ?? addressOf(url))) await gate(`http.fetch(${url})`, `network:${init?.socketPath ?? hostOf(url)}`)
         return claude.http.fetch(url, init)
       },
     },
@@ -69,37 +94,49 @@ export function checkingGrants(claude: Claude, grants: Grants): Claude {
         await gate('session.messages', 'conversation')
         return claude.session.messages(...args)
       }) as Claude['session']['messages'],
-      append: (async (args: Parameters<Claude['session']['append']>[0]) => {
-        await gate('session.append', 'prompt')
+      append: async (args: Parameters<Claude['session']['append']>[0]) => {
+        await gate('send', 'prompt')
         return claude.session.append(args)
-      }) as Claude['session']['append'],
+      },
+      send: async (args: Parameters<Claude['session']['send']>[0]) => {
+        await gate('send', 'prompt')
+        return claude.session.send(args)
+      },
     },
     prompt: {
-      submit: (async (args: Parameters<Claude['prompt']['submit']>[0]) => {
-        await gate('session.submit', 'prompt')
+      submit: async (args: Parameters<Claude['prompt']['submit']>[0]) => {
+        await gate('send', 'prompt')
         return claude.prompt.submit(args)
-      }) as Claude['prompt']['submit'],
+      },
+    },
+    cmod: {
+      async call(args) {
+        const named = args.to === cmodPluginName ? conversationCalls[args.method] : undefined
+        const given = args.method === conversationMethods.act && isObject(args.input) ? String(args.input['action']) : undefined
+        const action = given !== undefined && isAct(given) ? given : undefined
+        if (named !== undefined) await gate(action ?? named, action === undefined ? 'conversation' : actPermission(action, isObject(args.input) ? args.input['input'] : undefined))
+        return claude.cmod.call(args)
+      },
     },
     model: {
-      complete: (async (...args: Parameters<Claude['model']['complete']>) => {
+      complete: async (...args: Parameters<Claude['model']['complete']>) => {
         await gate('model.complete', 'model')
         return claude.model.complete(...args)
-      }) as Claude['model']['complete'],
+      },
     },
     agent: {
       ...claude.agent,
       async spawn(args) {
-        await gate('agent.spawn', 'agents')
+        await gate('startTask', 'tasks')
         return claude.agent.spawn(args)
       },
     },
     tool: {
       ...claude.tool,
-      call: (async (input: Parameters<Claude['tool']['call']>[0]) => {
-        const item = startsTurns.includes(input.tool) ? 'prompt' : ownSchedule.includes(input.tool) ? undefined : 'tools'
-        await gate(`tool.call(${input.tool})`, item)
+      call: async (input: Parameters<Claude['tool']['call']>[0]) => {
+        await gate(`tool.call(${input.tool})`, toolPermission(input.tool))
         return claude.tool.call(input)
-      }) as Claude['tool']['call'],
+      },
     },
   }
 }
@@ -112,8 +149,8 @@ function spawned(started: Promise<Stream>): Stream {
   const stream = {
     next: async () => (await started).next(),
     async return(value: never) {
-      const running = await started.catch(() => undefined)
-      return (await running?.return?.(value)) ?? { done: true as const, value }
+      const [start] = await Promise.allSettled([started])
+      return start.status === 'fulfilled' ? start.value.return(value) : { done: true as const, value }
     },
     [Symbol.asyncIterator]: () => stream,
     result,
@@ -144,7 +181,10 @@ function readItem(grants: Grants, path: string): string | undefined {
 
 function writeItem(grants: Grants, path: string): string | undefined {
   const root = grants.projectRoot()
-  if (configFiles.some((file) => `${root}/${file}` === path)) return 'config'
+  const settingsFiles = [...projectSettingsFiles.map((file) => `${root}/${file}`), ...(grants.configRoot === undefined ? [] : [`${grants.configRoot}/settings.json`])]
+  if (settingsFiles.includes(path)) {
+    throw new PermissionRefused(`${grants.name} writes ${path} by hand. Change Claude Code's settings with settings.user.update, settings.project.update, or settings.local.update, which keep the person's own edits and take the mod's values out when it is removed.`)
+  }
   if (grants.freeFolders().some((folder) => relativePath(folder, path) !== undefined)) return undefined
   return `files:${path}`
 }
@@ -287,11 +327,11 @@ function programOf(argv: readonly string[]): string {
 }
 
 function hostOf(url: string): string {
-  try {
-    return new URL(url).hostname
-  } catch {
-    return url
-  }
+  return URL.canParse(url) ? new URL(url).hostname : url
+}
+
+function addressOf(url: string): string {
+  return URL.canParse(url) ? new URL(url).host : url
 }
 
 function expanded(path: string, home: string | undefined): string {

package/src/runtime/hooks.ts

@@ -1,19 +1,22 @@
 import type { Args, ClassicHookInputs, EventResult, Frozen } from 'claude-code'
-import type { HookAnswer, HookInput, ModEvent, ModHook } from '../mod.js'
+import type { Hook, HookAnswer, HookInput, HookListener } from '../mod.js'
 import { configFolders } from '../records.js'
 import type { Claude } from './claude.js'
 import type { RoutedHook } from './router.js'
+import type { Failure } from './toaster.js'
 import { reservedKeys, toolInputOf, type ToolCalls } from './tool-calls.js'
 import { callEffects, inputOf, type CallBase, type FileAccess } from '../utils/call-effects.js'
 import { dynamicPattern } from '../utils/parse-shell.js'
+import { isMissing } from '../utils/paths.js'
 import { messageOf } from '../utils/text.js'
 
 export type RoutedEvent =
-  | `classic.${Exclude<ModEvent, 'PreToolUse'>}`
+  | `classic.${Exclude<Hook, 'PreToolUse'>}`
   | 'tool.check'
   | 'tool.call'
   | 'prompt.submit'
   | 'prompt.context'
+  | 'prompt.attachment'
   | 'command.run'
   | 'session.measure'
   | 'skill.prompt'
@@ -22,6 +25,10 @@ export type RoutedEvent =
   | 'ui.scroll'
   | 'ui.close'
   | 'cmod.call'
+  | 'session.append'
+  | 'session.compact'
+  | 'session.receive'
+  | 'agent.spawn'
 
 export const permissionEvents: readonly RoutedEvent[] = ['tool.check', 'classic.PermissionRequest']
 
@@ -31,28 +38,43 @@ type CallFiles = HookInput<'PreToolUse'>['files']
 
 const flags: readonly string[] = ['suppressOriginalPrompt', 'reloadSkills', 'retry']
 
-const readFields: Record<ModEvent, readonly string[]> = {
+const readFields: Record<Hook, readonly string[]> = {
+  Setup: ['additionalContext'],
   SessionStart: ['additionalContext', 'initialUserMessage', 'sessionTitle', 'watchPaths', 'reloadSkills'],
   SessionEnd: [],
   UserPromptSubmit: ['additionalContext', 'sessionTitle', 'suppressOriginalPrompt'],
+  UserPromptExpansion: ['additionalContext', 'suppressOriginalPrompt'],
   InstructionsLoaded: [],
+  ConfigChange: [],
+  DirectoryAdded: [],
+  PreModelSwitch: ['permissionDecision', 'permissionDecisionReason'],
+  PostModelSwitch: ['additionalContext'],
   PreToolUse: ['additionalContext', 'permissionDecision', 'permissionDecisionReason', 'updatedInput'],
   PermissionRequest: ['decision'],
   PermissionDenied: ['retry'],
   PostToolUse: ['additionalContext', 'updatedToolOutput', 'updatedMCPToolOutput'],
   PostToolUseFailure: ['additionalContext'],
   PostToolBatch: ['additionalContext'],
+  MessageDisplay: ['displayContent'],
   SubagentStart: ['additionalContext'],
   SubagentStop: ['additionalContext'],
+  TaskCreated: [],
+  TaskCompleted: [],
+  TeammateIdle: [],
+  Elicitation: [],
+  ElicitationResult: [],
   Notification: [],
   PreCompact: [],
+  PostCompact: [],
   Stop: ['additionalContext'],
   StopFailure: [],
   CwdChanged: [],
   FileChanged: [],
+  WorktreeCreate: ['worktreePath'],
+  WorktreeRemove: [],
 }
 
-export function classicHook<E extends Exclude<ModEvent, 'PreToolUse'>>(name: string, event: E, hook: ModHook<E>, claude: Claude, calls: ToolCalls): RoutedHook<RoutedEvent> {
+export function classicHook<E extends Exclude<Hook, 'PreToolUse'>>(name: string, event: E, hook: HookListener<E>, claude: Claude, calls: ToolCalls, report: (failure: Failure) => void): RoutedHook<RoutedEvent> {
   const hookInputOf = async (e: unknown): Promise<unknown> => {
     if (event !== 'PostToolUse' && event !== 'PostToolUseFailure') return e
     const input = e as ClassicHookInputs['PostToolUse' | 'PostToolUseFailure']
@@ -67,9 +89,8 @@ export function classicHook<E extends Exclude<ModEvent, 'PreToolUse'>>(name: str
   }
   const routed = async (e: unknown, next: (e: unknown) => Promise<unknown>) => {
     const ours = await resultOf(e).catch((error: unknown): ClassicFields | undefined => {
-      const reason = `${name}: the ${event} hook failed: ${messageOf(error)}`
-      if (event === 'PermissionRequest') return { decision: { behavior: 'deny', message: reason } }
-      claude.ui.log(reason)
+      if (event === 'PermissionRequest') return { decision: { behavior: 'deny', message: `${name}: the ${event} hook failed: ${messageOf(error)}` } }
+      report({ id: `hook:${event}`, message: `The ${event} hook failed`, error })
       return undefined
     })
     if (ours === undefined) return next(e)
@@ -82,7 +103,7 @@ type HeldDecision = { readonly decision: 'allow' | 'ask'; readonly reason?: stri
 
 export type HeldDecisions = Map<string, HeldDecision>
 
-export function preToolUseHook(name: string, hook: ModHook<'PreToolUse'>, claude: Claude, calls: ToolCalls, held: HeldDecisions | undefined): RoutedHook<'tool.call'> {
+export function preToolUseHook(name: string, hook: HookListener<'PreToolUse'>, claude: Claude, calls: ToolCalls, held: HeldDecisions | undefined): RoutedHook<'tool.call'> {
   return async (e, next) => {
     let ours: ClassicFields
     try {
@@ -167,11 +188,15 @@ async function preToolUseInput(name: string, envelope: Frozen<Args<'tool.call'>>
 
 async function callFiles(name: string, claude: Claude, use: CallBase, cwd: string): Promise<CallFiles> {
   try {
-    const home = await claude.env.home()
+    const [home, configRoot] = await Promise.all([claude.env.home(), claude.env.configHome()])
     if (home === undefined) throw new Error('HOME is not set, so ~ in a path has no meaning.')
-    const { shell, reads, writes } = callEffects(use, { cwd, home, fs: claude.fs })
+    const { shell, reads, writes } = callEffects(use, { cwd, home, ...(configRoot === undefined ? {} : { configRoot }), fs: claude.fs })
     const known = (accesses: FileAccess[]) => accesses.map(({ path }) => path).filter((path) => shell === undefined || !dynamicPattern.test(path))
-    const read = await Promise.all(known(reads).map(async (path) => ((await claude.fs.stat(path).catch(() => undefined))?.kind === 'file' ? [path] : [])))
+    const unchecked = (path: string) => (error: unknown) => {
+      if (!isMissing(error)) claude.ui.log(`${name}: the ${use.tool} call reads ${path}, which could not be checked: ${messageOf(error)}`, { to: 'debug' })
+      return undefined
+    }
+    const read = await Promise.all(known(reads).map(async (path) => ((await claude.fs.stat(path).catch(unchecked(path)))?.kind === 'file' ? [path] : [])))
     return { read: read.flat(), changed: known(writes) }
   } catch (error) {
     claude.ui.log(`${name}: the ${use.tool} call lists no files: ${messageOf(error)}`, { to: 'debug' })
@@ -179,7 +204,7 @@ async function callFiles(name: string, claude: Claude, use: CallBase, cwd: strin
   }
 }
 
-function classicResult(event: ModEvent, answer: HookAnswer): ClassicFields {
+function classicResult(event: Hook, answer: HookAnswer): ClassicFields {
   const result: ClassicFields = {}
   const unread = (field: string) => new Error(`it answered ${field}, which ${event} does not read. Remove it from the answer.`)
   if (event === 'PreToolUse') {
@@ -198,10 +223,10 @@ function classicResult(event: ModEvent, answer: HookAnswer): ClassicFields {
     if (field === 'hookEventName' || value === undefined || (value === false && flags.includes(field))) continue
     if (!readFields[event].includes(field)) throw unread(`hookSpecificOutput.${field}`)
     if (field === 'additionalContext') result['additionalContext'] = [value]
-    else if (field === 'permissionDecision') {
+    else if (field === 'permissionDecision' && event === 'PreToolUse') {
       const reason = specific.permissionDecisionReason ?? ''
       result[value as string] = value === 'allow' ? true : reason
-    } else if (field !== 'permissionDecisionReason') result[field] = value
+    } else if (field !== 'permissionDecisionReason' || event !== 'PreToolUse') result[field] = value
   }
   return result
 }

package/src/runtime/installer.ts

@@ -7,7 +7,7 @@ import { Box, Button, drawWith, Input, Text } from '../ui/elements.js'
 import { messageOf } from '../utils/text.js'
 import type { Claude } from './claude.js'
 
-export const installerPaneId = 'cmod-installer'
+export const installerPaneOf = (name: string): string => `installer-${name.replace(/[^A-Za-z0-9_-]/g, '_')}`.slice(0, 64)
 
 export type Consent = {
   readonly install: string
@@ -33,6 +33,7 @@ export type Installer = {
 }
 
 export function createInstaller(name: string, claude: () => Claude): Installer {
+  const paneId = installerPaneOf(name)
   let page: Page | undefined
   let isOpen = false
 
@@ -48,7 +49,7 @@ export function createInstaller(name: string, claude: () => Claude): Installer {
     })
     if (!isOpen) {
       isOpen = true
-      await claude().ui.open({ id: installerPaneId, title: `Install ${name}`, focus: true, holdToasts: true, closeOnEscape: true })
+      await claude().ui.open({ id: paneId, title: `Install ${name}`, focus: true, holdToasts: true, closeOnEscape: true })
     }
     claude().ui.invalidate('ui.render')
     return answer
@@ -60,12 +61,12 @@ export function createInstaller(name: string, claude: () => Claude): Installer {
   const bullet = (text: string) => Text({ children: [Text({ color: 'claude', children: '◆ ' }), text] })
 
   return {
-    draws: (e) => e.component === 'Pane' && e.requestId === installerPaneId,
+    draws: (e) => e.component === 'Pane' && e.requestId === paneId,
     draw(e) {
       return drawWith(claude().ui.resolve(e), () => page?.draw(e.props as Frozen<RenderPropsOf['Pane']>) ?? Text({ dimColor: true, children: `${name} is installing.` }))
     },
     closed(id) {
-      if (id !== installerPaneId) return
+      if (id !== paneId) return
       isOpen = false
       page?.cancel()
     },
@@ -102,12 +103,12 @@ export function createInstaller(name: string, claude: () => Claude): Installer {
               `${name} needs ${missing.length === 1 ? 'one setting' : `${missing.length} settings`}:`,
               missing.map(([key, option]) => {
                 const label = Text({ children: [Text({ bold: true, children: option.title }), option.description === '' ? '' : Text({ dimColor: true, children: `  ${option.description}` })] })
-                if (option.kind === 'secret') return Box({ flexDirection: 'column', children: [label, Text({ dimColor: true, children: `Set it in /config, where Claude Code keeps it in your keychain, then press Next.` })] })
+                if (option.type === 'secret') return Box({ flexDirection: 'column', children: [label, Text({ dimColor: true, children: `Set it in /config, where Claude Code keeps it in your keychain, then press Next.` })] })
                 const failure = failures.get(key)
                 const field = Input({
                   key: `option:${key}`,
                   label: '› ',
-                  placeholder: option.kind === 'choice' ? (option.choices ?? []).join(', ') : option.kind === 'toggle' ? 'true or false' : option.kind === 'list' ? 'comma-separated' : '',
+                  placeholder: option.type === 'choice' ? (option.choices ?? []).join(', ') : option.type === 'toggle' ? 'true or false' : option.type === 'list' ? 'comma-separated' : '',
                   value: saved.get(key) ?? '',
                   submitLabel: 'save',
                   onSubmit: (value: string) =>
@@ -131,7 +132,7 @@ export function createInstaller(name: string, claude: () => Claude): Installer {
       )
     },
     step(mod, step, index, total) {
-      let notice: string | undefined
+      let notice: { readonly color: 'warning' | 'error'; readonly text: string } | undefined
       return show<boolean>(
         (answer) => ({
           draw: (props) => {
@@ -142,16 +143,17 @@ export function createInstaller(name: string, claude: () => Claude): Installer {
               body = Text({ color: 'error', children: `The ${step.title} step could not draw: ${messageOf(error)}` })
             }
             const next = async () => {
-              const isDone = await Promise.resolve(step.isDone(mod)).catch(() => false)
-              if (isDone) answer(true)
-              else {
-                notice = `Finish ${step.title} first.`
-                claude().ui.invalidate('ui.render')
+              try {
+                if (await step.isDone(mod)) return answer(true)
+                notice = { color: 'warning', text: `Finish ${step.title} first.` }
+              } catch (error) {
+                notice = { color: 'error', text: `The ${step.title} step's isDone failed: ${messageOf(error)}` }
               }
+              claude().ui.invalidate('ui.render')
             }
             return frame(
               `${step.title}  (${index} of ${total})`,
-              [body, ...(notice === undefined ? [] : [Text({ color: 'warning', children: notice })])],
+              [body, ...(notice === undefined ? [] : [Text({ color: notice.color, children: notice.text })])],
               [Button({ key: 'not-now', hotkey: 'n', label: 'Not now', onPress: () => answer(false) }), Button({ key: 'next', hotkey: 'x', label: index === total ? 'Finish' : 'Next', onPress: () => void next() })],
             )
           },
@@ -163,7 +165,7 @@ export function createInstaller(name: string, claude: () => Claude): Installer {
       page = undefined
       if (!isOpen) return
       isOpen = false
-      await claude().ui.close({ id: installerPaneId })
+      await claude().ui.close({ id: paneId })
     },
   }
 }