@cmodjs/core 0.1.13 → 0.2.0

package/runtime/options.js

@@ -0,0 +1,100 @@
+import { fitsOption, isUnset } from '../options.js';
+import { configFolders } from '../records.js';
+import { listed, messageOf } from '../utils/text.js';
+export class MissingOptions extends Error {
+    keys;
+    titles;
+    constructor(keys, titles) {
+        super(`it needs ${listed(titles)}`);
+        this.keys = keys;
+        this.titles = titles;
+    }
+}
+export function createOptions({ name, declared, fromClaude, claude, changed }) {
+    let values = merged(declared, fromClaude, {}, new Set());
+    let locked;
+    let loadedRoot;
+    const readLocked = async () => {
+        if (Object.keys(declared).length === 0)
+            return new Set();
+        const rows = await claude.config.list().catch((error) => {
+            claude.ui.log(`${name} could not read /config, so a project's options.json may override a value your organization set: ${messageOf(error)}`, { to: 'debug' });
+            return [];
+        });
+        return new Set(rows.filter((row) => row.isLocked && row.key.startsWith(`${name}.`)).map((row) => row.key.slice(name.length + 1)));
+    };
+    const readProject = async (root) => {
+        const env = { HOME: await claude.env.home(), CLAUDE_CONFIG_DIR: await claude.env.configHome() };
+        const project = configFolders(env, name, root).find(({ tier }) => tier === 'project');
+        if (project === undefined)
+            return {};
+        const path = `${project.folder}/options.json`;
+        if (!(await claude.fs.exists(path)))
+            return {};
+        const ignore = (reason) => claude.ui.log(`${path} ${reason}`);
+        let file;
+        try {
+            file = JSON.parse(await claude.fs.read(path));
+        }
+        catch (error) {
+            ignore(`is not JSON (${messageOf(error)}). Fix the file; ${name} uses its other options until then.`);
+            return {};
+        }
+        if (typeof file !== 'object' || file === null || Array.isArray(file)) {
+            ignore('is not a JSON object. Write one, such as { "branch": "main" }.');
+            return {};
+        }
+        const kept = {};
+        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.kind === 'secret')
+                ignore(`sets ${key}, a secret, and a project file is committed for everyone to read. Remove it, and set it in /config.`);
+            else {
+                const misfit = fitsOption(option, value);
+                if (misfit === undefined)
+                    kept[key] = value;
+                else
+                    ignore(`sets ${key} to ${JSON.stringify(value)}, and ${option.title} ${misfit}.`);
+            }
+        }
+        return kept;
+    };
+    return {
+        get values() {
+            return values;
+        },
+        get missing() {
+            return Object.entries(declared)
+                .filter(([key, option]) => option.default === undefined && isUnset(values[key]))
+                .map(([key]) => key);
+        },
+        async load(root) {
+            if (Object.keys(declared).length === 0)
+                return;
+            locked ??= await readLocked();
+            const project = await readProject(root);
+            const isFirst = loadedRoot === undefined;
+            loadedRoot = root;
+            const next = merged(declared, fromClaude, project, locked);
+            if (!isFirst && JSON.stringify(next) === JSON.stringify(values))
+                return;
+            values = next;
+            if (!isFirst)
+                changed();
+        },
+    };
+}
+function merged(declared, fromClaude, project, locked) {
+    return Object.freeze(Object.fromEntries(Object.entries(declared).map(([key, option]) => [key, valueOf(key, option, fromClaude[key], project, locked)])));
+}
+function valueOf(key, option, own, project, locked) {
+    if (locked.has(key))
+        return own;
+    if (Object.hasOwn(project, key))
+        return project[key];
+    if (!isUnset(own) && fitsOption(option, own) === undefined)
+        return Array.isArray(own) ? Object.freeze([...own]) : own;
+    return option.default ?? (option.kind === 'list' ? Object.freeze([]) : option.kind === 'number' ? undefined : '');
+}

package/runtime/state.d.ts

@@ -11,6 +11,7 @@ export type StateOptions = {
 export type ModState<State extends object> = {
     readonly state: State;
     readonly root: string;
+    changed(): void;
     load(): Promise<void>;
     moveTo(root: string): Promise<void>;
     switchSession(session: string, source: ClassicHookInputs['SessionStart']['source']): Promise<void>;

package/runtime/state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/runtime/state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAGpD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAQzC,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAA;CAC7B,CAAA;AAED,MAAM,MAAM,QAAQ,CAAC,KAAK,SAAS,MAAM,IAAI;IAC3C,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACrB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACnC,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,CAAC,cAAc,CAAC,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACnG,CAAA;AAUD,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAIvE;AAED,wBAAgB,WAAW,CAAC,KAAK,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,YAAY,GAAG,QAAQ,CAAC,KAAK,CAAC,CAyI1I"}
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/runtime/state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAEpD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAQzC,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAA;CAC7B,CAAA;AAED,MAAM,MAAM,QAAQ,CAAC,KAAK,SAAS,MAAM,IAAI;IAC3C,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,OAAO,IAAI,IAAI,CAAA;IACf,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACrB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACnC,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,CAAC,cAAc,CAAC,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACnG,CAAA;AAQD,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAIvE;AAED,wBAAgB,WAAW,CAAC,KAAK,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,YAAY,GAAG,QAAQ,CAAC,KAAK,CAAC,CAoF1I"}

package/runtime/state.js

@@ -1,7 +1,5 @@
-import { configFolder, configFolders } from '../records.js';
 import { messageOf } from '../utils/text.js';
 const lifetimes = ['memory', 'session', 'project', 'global'];
-const savedLifetimes = ['session', 'project', 'global'];
 const keptPerValue = 20;
 const listeners = new WeakMap();
 export function onStateChange(state, listener) {
@@ -17,7 +15,6 @@ export function createState({ name, initial, session, root, claude, changed: red
     };
     const declared = declaredGroups(name, initial);
     const current = copied(declared);
-    let defaults = declared;
     let projectRoot = root;
     let sessionId = session;
     let turn = Promise.resolve();
@@ -38,62 +35,6 @@ export function createState({ name, initial, session, root, claude, changed: red
         for (const oldest of owners.slice(0, -keptPerValue))
             await claude.store.delete(oldest);
     };
-    const fileValues = (path, tier, text, systemPath) => {
-        const values = [];
-        const ignore = (reason) => claude.ui.log(`${path} ${reason}`);
-        let file;
-        try {
-            file = JSON.parse(text);
-        }
-        catch (error) {
-            ignore(`is not JSON (${messageOf(error)}). Fix the file, then run /reload-plugins.`);
-            return values;
-        }
-        if (!isPlainObject(file)) {
-            ignore('is not a JSON object. Write one, such as { "global": { "key": "value" } }.');
-            return values;
-        }
-        for (const [group, entries] of Object.entries(file)) {
-            if (!isLifetime(group)) {
-                ignore(`sets ${group}, which ${name} does not declare. Remove it, or use one of: ${savedLifetimes.join(', ')}.`);
-                continue;
-            }
-            if (group === 'memory') {
-                ignore('sets memory, and memory values are never saved, so a file cannot set them. Remove it.');
-                continue;
-            }
-            if (!isPlainObject(entries)) {
-                ignore(`sets ${group} to ${typeOf(entries)}. Write an object of values, such as { "${group}": { "key": "value" } }.`);
-                continue;
-            }
-            for (const [key, value] of Object.entries(entries)) {
-                const choices = Object.keys(declared[group]);
-                const wanted = typeOf(declared[group][key]);
-                if (!Object.hasOwn(declared[group], key))
-                    ignore(`sets ${group}.${key}, which ${name} does not declare. ${choices.length === 0 ? 'Remove it.' : `Remove it, or use one of: ${choices.join(', ')}.`}`);
-                else if (tier === 'project' && group === 'global')
-                    ignore(`sets ${group}.${key}, and one repository cannot change a value for every project. Move it to ${systemPath}.`);
-                else if (typeOf(value) !== wanted)
-                    ignore(`sets ${group}.${key} to ${typeOf(value)}, and ${name} keeps ${wanted} there. Write ${wanted}, or remove it.`);
-                else
-                    values.push([group, key, frozen(name, `${group}.${key}`, value)]);
-            }
-        }
-        return values;
-    };
-    const readDefaults = async (nextRoot) => {
-        const env = { HOME: await claude.env.home(), CLAUDE_CONFIG_DIR: await claude.env.configHome() };
-        const systemPath = `${configFolder(env, name)}/state.json`;
-        const next = copied(declared);
-        for (const { tier, folder } of configFolders(env, name, nextRoot)) {
-            const path = `${folder}/state.json`;
-            if (!(await claude.fs.exists(path)))
-                continue;
-            for (const [lifetime, key, value] of fileValues(path, tier, await claude.fs.read(path), systemPath))
-                next[lifetime][key] = value;
-        }
-        return next;
-    };
     const loadGroups = async (only, next) => {
         const loaded = [];
         for (const lifetime of only) {
@@ -102,9 +43,8 @@ export function createState({ name, initial, session, root, claude, changed: red
         }
         projectRoot = next.root;
         sessionId = next.session;
-        defaults = next.defaults;
         for (const [lifetime, key, saved] of loaded)
-            current[lifetime][key] = saved === undefined ? defaults[lifetime][key] : frozen(name, `${lifetime}.${key}`, saved);
+            current[lifetime][key] = saved === undefined ? declared[lifetime][key] : frozen(name, `${lifetime}.${key}`, saved);
         changed();
     };
     const copySession = async (nextSession) => {
@@ -139,14 +79,15 @@ export function createState({ name, initial, session, root, claude, changed: red
         get root() {
             return projectRoot;
         },
-        load: () => inTurn(async () => loadGroups(lifetimes, { root: projectRoot, session: sessionId, defaults: await readDefaults(projectRoot) })),
-        moveTo: (nextRoot) => inTurn(async () => (nextRoot === projectRoot ? undefined : loadGroups(['project'], { root: nextRoot, session: sessionId, defaults: await readDefaults(nextRoot) }))),
+        changed,
+        load: () => inTurn(() => loadGroups(lifetimes, { root: projectRoot, session: sessionId })),
+        moveTo: (nextRoot) => inTurn(async () => (nextRoot === projectRoot ? undefined : loadGroups(['project'], { root: nextRoot, session: sessionId }))),
         switchSession: (nextSession, source) => inTurn(async () => {
             if (nextSession === sessionId)
                 return;
             if (source === 'fork')
                 await copySession(nextSession);
-            return loadGroups(['memory', 'session'], { root: projectRoot, session: nextSession, defaults });
+            return loadGroups(['memory', 'session'], { root: projectRoot, session: nextSession });
         }),
     };
 }
@@ -168,17 +109,6 @@ function copied(groups) {
 function isLifetime(group) {
     return lifetimes.includes(group);
 }
-function typeOf(value) {
-    if (value === null)
-        return 'null';
-    if (Array.isArray(value))
-        return 'an array';
-    if (typeof value === 'object')
-        return 'an object';
-    if (value === undefined)
-        return 'nothing';
-    return `a ${typeof value}`;
-}
 function frozen(name, path, value) {
     const isArray = Array.isArray(value);
     if (!isArray && !isPlainObject(value))

package/src/installer.ts

@@ -0,0 +1,17 @@
+import type { Frozen, RenderElement, RenderPropsOf } from 'claude-code'
+import type { Mod } from './mod.js'
+
+export type Step<State extends object = Record<never, never>> = {
+  readonly id: string
+  readonly title: string
+  render(mod: Mod<State>, props: Frozen<RenderPropsOf['Pane']>): RenderElement
+  isDone(mod: Mod<State>): boolean | Promise<boolean>
+}
+
+const stepId = /^[A-Za-z0-9_-]{1,64}$/
+
+export function defineStep<State extends object = Record<never, never>>(step: Step<State>): Step<State> {
+  if (!stepId.test(step.id)) throw new Error(`defineStep: "${step.id}" is not a step id. Use 1 to 64 letters, digits, "_", or "-".`)
+  if (step.title.trim() === '') throw new Error(`defineStep: the step "${step.id}" needs a title, the line the installer shows above it.`)
+  return step
+}

package/src/jobs/context.ts

@@ -14,7 +14,7 @@ type Session = Omit<Workspace, 'projectRoot' | 'cwd'>
 
 type Stream = HookStream<ProcessSpawnChunk, ProcessSpawnResult>
 
-export function workspaceReader({ claude }: JobContext): () => Promise<Workspace> {
+export function workspaceReader({ mod: { claude } }: JobContext): () => Promise<Workspace> {
   let session: Promise<Session> | undefined
   return async () => {
     session ??= readSession(claude)
@@ -40,7 +40,7 @@ export function afterCall<State extends object>(
   failed: (error: unknown) => readonly string[],
 ): void {
   const readWorkspace = workspaceReader(job)
-  job.on('tool.call', async (e, next) => {
+  job.mod.claude.on('tool.call', async (e, next) => {
     const before = Promise.all([useOf(job, e), readWorkspace()])
     await before.catch(() => undefined)
     const result = await next(e)
@@ -58,7 +58,8 @@ export function modOf<State extends object>(job: JobContext<State>, { call, fold
   return modWithin(job, deadline, async () => workspace.scope?.workTreeOf(call !== undefined && 'path' in call ? call.path : folder))
 }
 
-export function modWithin<State extends object>({ mod, claude }: JobContext<State>, deadline: Deadline, workTree: () => Promise<string | undefined> = async () => undefined): Mod<State> {
+export function modWithin<State extends object>({ mod }: JobContext<State>, deadline: Deadline, workTree: () => Promise<string | undefined> = async () => undefined): Mod<State> {
+  const { claude } = mod
   const within = <Value>(call: string, task: Promise<Value>) => beforeDeadline(claude, deadline, call, task)
   const folderOf = async (cwd: string | undefined) => {
     const folder = cwd ?? (await workTree())
@@ -79,6 +80,7 @@ export function modWithin<State extends object>({ mod, claude }: JobContext<Stat
       list: (path) => within('mod.fs.list', mod.fs.list(path)),
       exists: (path) => within('mod.fs.exists', mod.fs.exists(path)),
       stat: (path, options) => within('mod.fs.stat', mod.fs.stat(path, options)),
+      find: (glob) => within('mod.fs.find', mod.fs.find(glob)),
     },
     http: { fetch: (url, init) => within('mod.http.fetch', mod.http.fetch(url, init)) },
     dependencies: dependencyCalls(claude, within),

package/src/jobs/permissions.ts

@@ -37,7 +37,7 @@ export function permissions<State extends object = Record<never, never>>(rules:
       }
     }
 
-    job.on('tool.check', async (e, next) => {
+    job.mod.claude.on('tool.check', async (e, next) => {
       const [below, ours] = await Promise.all([next(e), verdictOf(e)])
       return ours === undefined ? below : stricterVerdict<Verdict>(below, ours)
     })

package/src/jobs/program.ts

@@ -1,4 +1,5 @@
 import type { Job } from '../mod.js'
+import { PermissionRefused } from '../runtime/grants.js'
 import { messageOf } from '../utils/text.js'
 
 export type Program = {
@@ -12,7 +13,8 @@ const backoffSeconds = [1, 2, 4, 8, 16] as const
 
 export function program(options: { readonly command: readonly string[]; readonly environment?: Record<string, string> }): Job<Program> {
   const { command, environment } = options
-  return ({ mod, claude, announce }) => {
+  return ({ mod, announce }) => {
+    const { claude } = mod
     const [executable] = command
     if (executable === undefined) throw new Error(`${mod.name}: the program has no command. Name the program on PATH and its arguments, such as ['preview-server', '--port', '0'].`)
     let state: Program['state'] = 'stopped'
@@ -53,6 +55,7 @@ export function program(options: { readonly command: readonly string[]; readonly
           for (const waiter of waiting.splice(0)) waiter.resolve(address)
         }
       } catch (error) {
+        if (error instanceof PermissionRefused) return stop(`${messageOf(error)} Add it, then run /reload-plugins.`)
         lastError = messageOf(error)
       }
       address = undefined

package/src/jobs/prompt.ts

@@ -26,7 +26,7 @@ export function prompt<State extends object = Record<never, never>>({ name, prom
   return (job) => {
     job.reserveName('prompt', name, `prompt: ${job.mod.name} adds the name "${name}" two times. Give each prompt its own name.`)
 
-    const log = (reason: string) => job.claude.ui.log(`prompt "${name}" added nothing: ${reason}`, { to: 'debug' })
+    const log = (reason: string) => job.mod.claude.ui.log(`prompt "${name}" added nothing: ${reason}`, { to: 'debug' })
     const textFor = async (input: PromptInput, mod: Mod<State>) => {
       try {
         const value = typeof text === 'string' ? text : await text(input, mod)
@@ -61,12 +61,12 @@ function addKeptCurrent<State extends object>(job: JobContext<State>, name: stri
   let isQueued = false
   let updates = Promise.resolve()
 
-  job.on('classic.SessionStart', (e, next) => {
+  job.mod.claude.on('classic.SessionStart', (e, next) => {
     hasStarted = e.source === 'resume' || e.source === 'compact'
     if (!hasStarted) given = undefined
     return next(e)
   })
-  job.on('prompt.context', async (e, next) => {
+  job.mod.claude.on('prompt.context', async (e, next) => {
     const below = await next(e)
     hasStarted = true
     if (below.blocks.some((block) => block.name === name)) {
@@ -83,7 +83,7 @@ function addKeptCurrent<State extends object>(job: JobContext<State>, name: stri
     const value = await textFor()
     if (value === undefined || value === given) return
     given = value
-    await job.claude.session.append({ message: { type: 'user', content: [{ type: 'text', text: `# ${name}\n${value}` }] } }).then((added) => {
+    await job.mod.claude.session.append({ message: { type: 'user', content: [{ type: 'text', text: `# ${name}\n${value}` }] } }).then((added) => {
       if (added.deny !== undefined) log(`Claude Code refused the new text: ${added.deny}`)
     })
   }
@@ -95,7 +95,7 @@ function addKeptCurrent<State extends object>(job: JobContext<State>, name: stri
 }
 
 function addAfterUserPrompts(job: JobContext, when: RegExp | ((userPrompt: string) => boolean), textFor: (userPrompt: string) => Promise<string | undefined>, log: (reason: string) => void): void {
-  job.on('prompt.submit', async (e, next) => {
+  job.mod.claude.on('prompt.submit', async (e, next) => {
     let value: string | undefined
     try {
       if (typeof when === 'function' ? when(e.text) : e.text.search(when) >= 0) value = await textFor(e.text)

package/src/jobs/schedule.ts

@@ -10,7 +10,8 @@ export function schedule<State extends object = Record<never, never>>(entry: Sch
   if (typeof entry !== 'function') checked(entry)
 
   return (job) => {
-    const { mod, claude } = job
+    const { mod } = job
+    const { claude } = mod
     const order = scheduleCounts.get(mod) ?? 0
     scheduleCounts.set(mod, order + 1)
     const storeKey = `cmod:schedule:${order}`

package/src/jobs/slash-command.ts

@@ -20,7 +20,8 @@ export function slashCommand<State extends object = Record<never, never>>(option
 }): Job<void, State> {
   const { name, description, argumentHint, immediate, reply } = options
   return (job) => {
-    const { mod, claude, announce, reserveName } = job
+    const { mod, announce, reserveName } = job
+    const { claude } = mod
     if (!commandName.test(name)) throw new Error(`${mod.name}: "${name}" is not a slash command name. Use 1 to 64 letters, digits, "_", or "-", without the slash.`)
     reserveName('slashCommand', name, `${mod.name}: the slash command /${name} is already added. Give each slashCommand its own name.`)
 
@@ -36,7 +37,7 @@ export function slashCommand<State extends object = Record<never, never>>(option
     announce(`/${name}`)
 
     const replyMod = modWithin(job, deadline)
-    job.on('command.run', async (e, next) => {
+    claude.on('command.run', async (e, next) => {
       if (e.command !== registered) return next(e)
       try {
         return answerOf(await reply({ args: e.args, positionals: splitWords(e.args) }, replyMod))

package/src/jobs/status-line.ts

@@ -17,7 +17,8 @@ export function statusLine<State extends object = Record<never, never>>(options:
 }): Job<void, State> {
   const { text, interval = 10000 } = options
   return (job) => {
-    const { mod, claude, announce, reserveName } = job
+    const { mod, announce, reserveName } = job
+    const { claude } = mod
     if (!(interval >= 1)) throw new Error(`${mod.name}: the status line interval is ${interval}. Give it in milliseconds, 1 or more.`)
     reserveName('statusLine', '', `${mod.name}: a status line is already added. A mod has one status line: join the texts in one statusLine.`)
 
@@ -48,7 +49,7 @@ export function statusLine<State extends object = Record<never, never>>(options:
     }
 
     announce('a status line')
-    job.on('session.measure', (e, next) => {
+    claude.on('session.measure', (e, next) => {
       refresh()
       return next(e)
     })

package/src/jobs/tool.ts

@@ -16,7 +16,8 @@ export function tool<const Schema extends object = { type: 'object' }, State ext
 }): Job<{ readonly name: string }, State> {
   const { name, description, inputSchema, execute } = options
   return (job) => {
-    const { mod, claude, announce, reserveName } = job
+    const { mod, announce, reserveName } = job
+    const { claude } = mod
     if (!toolName.test(name)) throw new Error(`${mod.name}: "${name}" is not a tool name. Use 1 to 64 letters, digits, "_", or "-".`)
     const properties = (inputSchema as { properties?: object } | undefined)?.properties ?? {}
     const reserved = reservedKeys.filter((key) => Object.hasOwn(properties, key))
@@ -36,7 +37,7 @@ export function tool<const Schema extends object = { type: 'object' }, State ext
     announce(`the ${name} tool`)
 
     const executeMod = modWithin(job, toolDeadline)
-    job.on('tool.call', async (e, next) => {
+    claude.on('tool.call', async (e, next) => {
       if (e.tool !== registered) return next(e)
       const input = toolInputOf(e)
       const { valid, errors } = validator.validate(input)

package/src/mod.ts

@@ -21,13 +21,15 @@ import type {
   ProcessSpawnRequest,
   ProcessSpawnResult,
   RenderElement,
-  Settings,
-  SettingsReadArgs,
+  SessionMessage,
   Timer,
   ToastOptions,
   UiScrollArgs,
   UiScrollResult,
 } from 'claude-code'
+import type { Step } from './installer.js'
+import { checkOptions, type Option, type Options, type OptionValues } from './options.js'
+import type { FlagPermission, ListPermission } from './records.js'
 import type { Claude } from './runtime/claude.js'
 import type { RoutedEvent } from './runtime/hooks.js'
 import type { RoutedHook } from './runtime/router.js'
@@ -125,9 +127,30 @@ export type HookOptions = {
   readonly timeoutMs?: number
 }
 
-export type Mod<State extends object = Record<never, never>> = {
+export type ScrollArgs = Omit<UiScrollArgs, 'to'> & { readonly to: Exclude<UiScrollArgs['to'], { requestId: string }> }
+
+export type ModClaude = Claude & {
+  on<N extends RoutedEvent>(event: N, hook: RoutedHook<N>): void
+}
+
+export type Metadata = Readonly<Record<string, string>>
+
+export type FileMatch = {
+  readonly path: string
+  readonly name?: string
+  readonly metadata: Metadata
+  readonly error?: string
+}
+
+type SessionMessages = {
+  (): Promise<SessionMessage[]>
+  (args: { readonly agentId: string }): Promise<SessionMessage[] | { readonly deny: string }>
+}
+
+export type Mod<State extends object = Record<never, never>, Declared extends Options = Options> = {
   readonly name: string
   readonly state: Readonly<State>
+  readonly options: OptionValues<Declared>
   readonly dataFolder: string
   on<E extends ModEvent>(event: E, hook: ModHook<E>, options?: HookOptions): void
   use<Handle>(job: Job<Handle, State>): Handle
@@ -138,7 +161,7 @@ export type Mod<State extends object = Record<never, never>> = {
     toast(text: string, options?: ToastOptions): void
     progress<T>(title: string, task: (report: (step: ProgressStep) => void) => Promise<T>): Promise<T>
     ask(question: string, options?: readonly string[] | AskOptions): Promise<string>
-    scroll(args: UiScrollArgs): Promise<UiScrollResult>
+    scroll(args: ScrollArgs): Promise<UiScrollResult>
   }
   readonly process: {
     run(argv: readonly string[], init?: ProcessRunInit): Promise<ProcessRunResult>
@@ -150,15 +173,21 @@ export type Mod<State extends object = Record<never, never>> = {
     list(path?: string): Promise<FsEntry[]>
     exists(path: string): Promise<boolean>
     stat(path: string, options?: FsStatOptions): Promise<FsStat>
+    find(glob: string | readonly string[]): Promise<readonly FileMatch[]>
+  }
+  readonly metadata: {
+    read(path: string): Promise<Metadata>
+    update(path: string, change: (metadata: Record<string, string>) => void): Promise<void>
   }
   readonly http: {
     fetch(url: string, init?: HttpInit): Promise<HttpResponse>
   }
   readonly settings: {
-    read(args?: SettingsReadArgs): Promise<Settings>
+    page(page: Pane<State>): void
+    open(pageId?: string): Promise<void>
   }
   readonly session: {
-    messages: Claude['session']['messages']
+    messages: SessionMessages
     append(text: string): Promise<void>
     submit(text: string): Promise<void>
   }
@@ -168,9 +197,14 @@ export type Mod<State extends object = Record<never, never>> = {
   readonly model: {
     complete(request: ModelCompleteRequest, options?: ModelCompleteOptions): Promise<ModelCompleteResult>
   }
+  readonly permissions: {
+    has(name: ListPermission, value: string): boolean
+    has(name: FlagPermission): boolean
+  }
   readonly projectRoot: string
   readonly cwd: string
   readonly dependencies: CmodDependencies
+  readonly claude: ModClaude
 }
 
 type StateGroups = {
@@ -184,17 +218,17 @@ type Api<Contract, State extends object> = {
   readonly [Method in keyof Contract]: Contract[Method] extends (input: infer Input) => infer Result ? (input: Input, mod: Mod<State>) => Result | Awaited<Result> : never
 }
 
-export type ModDefinition<State extends StateGroups = Record<never, never>, Name extends string = string> = {
+export type ModDefinition<State extends StateGroups = Record<never, never>, Name extends string = string, Declared extends Options = Record<never, Option>> = {
   readonly name: Name
   readonly state?: State
+  readonly options?: Declared
   readonly api?: Name extends keyof CmodDependencies ? Api<CmodDependencies[Name], State> : { readonly [method: string]: (input: never, mod: Mod<State>) => unknown }
-  setup(mod: Mod<State>): void | Promise<void>
+  readonly installer?: readonly Step<State>[]
+  setup(mod: Mod<State, Declared>): void | Promise<void>
 }
 
 export type JobContext<State extends object = Record<never, never>> = {
   readonly mod: Mod<State>
-  readonly claude: Claude
-  on<N extends RoutedEvent>(event: N, hook: RoutedHook<N>): void
   announce(feature: string): void
   reserveName(kind: string, name: string, taken: string): void
   readonly toolCalls: ToolCalls
@@ -202,7 +236,8 @@ export type JobContext<State extends object = Record<never, never>> = {
 
 export type Job<Handle, State extends object = Record<never, never>> = (context: JobContext<State>) => Handle
 
-export function defineMod<State extends StateGroups = Record<never, never>, Name extends string = string>(definition: ModDefinition<State, Name>): ModDefinition<State, Name> {
+export function defineMod<State extends StateGroups = Record<never, never>, Name extends string = string, const Declared extends Options = Record<never, Option>>(definition: ModDefinition<State, Name, Declared>): ModDefinition<State, Name, Declared> {
   if (definition.name.trim() === '') throw new Error('defineMod: the mod needs a name, such as the name in .claude-plugin/plugin.json.')
+  if (definition.options !== undefined) checkOptions(definition.name, definition.options)
   return definition
 }