@cmodjs/core 0.2.3 → 1.0.0

package/src/runtime/grants.ts

@@ -1,7 +1,9 @@
 import { 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 { conversationMethods } from './sessions.js'
 
 export type Grants = {
   readonly name: string
@@ -12,24 +14,50 @@ 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>>()
+
+export function programAddresses(mod: object): Set<string> {
+  const known = addressesOfPrograms.get(mod) ?? new Set<string>()
+  addressesOfPrograms.set(mod, known)
+  return known
+}
+
+const projectSettingsFiles: readonly string[] = ['.claude/settings.json', '.claude/settings.local.json', '.mcp.json']
 
 const startsTurns: readonly string[] = ['CronCreate']
 
 const ownSchedule: readonly string[] = ['CronDelete', 'CronList']
 
-async function checkGrant(grants: Grants, call: string, item: string | undefined): Promise<void> {
+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.send]: 'send',
+}
+
+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,54 +87,58 @@ 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)
       },
     },
-    config: {
-      ...claude.config,
-      set: (async (args: Parameters<Claude['config']['set']>[0]) => {
-        await gate('config.set', 'config')
-        return claude.config.set(args)
-      }) as Claude['config']['set'],
-    },
     session: {
       ...claude.session,
       messages: (async (...args: Parameters<Claude['session']['messages']>) => {
         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
+        if (named !== undefined) await gate(named, args.method === conversationMethods.send ? 'prompt' : 'conversation')
+        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]) => {
+      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)
         return claude.tool.call(input)
-      }) as Claude['tool']['call'],
+      },
     },
   }
 }
@@ -119,8 +151,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,
@@ -151,7 +183,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}`
 }
@@ -294,11 +329,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,15 +1,17 @@
 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'
@@ -22,6 +24,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,7 +37,7 @@ type CallFiles = HookInput<'PreToolUse'>['files']
 
 const flags: readonly string[] = ['suppressOriginalPrompt', 'reloadSkills', 'retry']
 
-const readFields: Record<ModEvent, readonly string[]> = {
+const readFields: Record<Hook, readonly string[]> = {
   SessionStart: ['additionalContext', 'initialUserMessage', 'sessionTitle', 'watchPaths', 'reloadSkills'],
   SessionEnd: [],
   UserPromptSubmit: ['additionalContext', 'sessionTitle', 'suppressOriginalPrompt'],
@@ -52,7 +58,7 @@ const readFields: Record<ModEvent, readonly string[]> = {
   FileChanged: [],
 }
 
-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 +73,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 +87,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 {
@@ -171,7 +176,11 @@ async function callFiles(name: string, claude: Claude, use: CallBase, cwd: strin
     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 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 +188,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') {

package/src/runtime/installer.ts

@@ -102,12 +102,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 +131,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 +142,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() })],
             )
           },