@cmodjs/core 0.3.0 → 1.0.0

package/runtime/lifecycle.js

@@ -1,36 +1,41 @@
-import { consentPath, dataFolder, finishStepsMethod, isAtLeast, marketplaceOf, oldestCmodFor, openPageMethod, parseConsent, pendingStepsMethod, parseEvent, permissionWords, readRecord, readSteps, scriptsSha256, settingsPagesMethod, storeFolder, updatesToTurnOn } from '../records.js';
-import { relativePath } from '../utils/paths.js';
-import { formatExit, listed, messageOf } from '../utils/text.js';
+import { hooks, PreToolUse } from '../mod.js';
+import { changelogPage, consentPath, dataFolder, finishStepsMethod, isAtLeast, marketplaceOf, oldestCmodFor, openPageMethod, parseConsent, pendingStepsMethod, parseEvent, permissionWords, readRecord, readSteps, recordPath, scriptsSha256, settingsPagesMethod, storeFolder, updatesToTurnOn } from '../records.js';
+import { ifMissing, relativePath } from '../utils/paths.js';
+import { firstLine, formatExit, listed, messageOf } from '../utils/text.js';
 import { beforeDeadline } from './deadline.js';
-import { answerCall, dependencyCalls, notInstalled } from './dependencies.js';
+import { announcedOf, announcementMs, announcementOf } from './announce.js';
+import { bind } from './bound.js';
+import { serveConversations } from './conversations.js';
+import { answerCall, cmodPluginName, dependencyCalls, notInstalled, withBareRefusals } from './dependencies.js';
+import { keepEngine } from './engine.js';
 import { classicHook, heldDecisionHook, permissionEvents, preToolUseHook, userSkillHook } from './hooks.js';
-import { checkedAnswer, checkingGrants, checksAnswers, checkWrite, isCovered, itemOf, passedDown } from './grants.js';
-import { locatingPrograms } from './programs.js';
-import { createModFiles } from './metadata.js';
+import { checkedAnswer, checkingGrants, checkSettings, checksAnswers, checkWrite, isCovered, itemOf, passedDown, programAddresses } from './grants.js';
+import { cmodError, lastLineOf, locatingPrograms, readLines } from './programs.js';
+import { createModFiles, resolvedPath } from './metadata.js';
 import { fitsOption } from '../options.js';
 import { createInstaller } from './installer.js';
 import { createOptions, MissingOptions } from './options.js';
 import { createRouter } from './router.js';
+import { conversationMethods, createSessionsClient } from './sessions.js';
+import { matches } from '../utils/matcher.js';
 import { createState } from './state.js';
+import { createToaster, showFailure } from './toaster.js';
 import { toolCalls } from './tool-calls.js';
-import { createProgress, createUi } from './ui.js';
-const cmodPluginName = 'cmod';
+import { createUi } from './ui.js';
+import { Progress } from '../ui/components.js';
+import { Box, Text } from '../ui/elements.js';
 const announcedKey = 'cmod:announced';
+const installId = 'cmod:install';
 const cmodCheckMs = 1000;
 const cmodWaitMs = 60_000;
-const sessionStartHoldMs = 10_000 - 1_000;
+const startHoldMs = 10_000 - 1_000;
 const dependencyCallMs = 30_000;
 const cannotStart = /failed to start: /;
-const missingPath = /(?:^|: )(?:ENOENT|ENOTDIR)\b/;
 const shellTools = ['Bash', 'PowerShell'];
 export async function readPlugin(claude) {
     const { name, root } = claude.plugin;
     const read = async (path) => {
-        const stat = await claude.fs.stat(path).catch((error) => {
-            if (missingPath.test(messageOf(error)))
-                return undefined;
-            throw error;
-        });
+        const stat = await claude.fs.stat(path).catch(ifMissing(undefined));
         return stat?.kind === 'file' ? claude.fs.read(path) : undefined;
     };
     const manifest = (await readJson(read, `${root}/.claude-plugin/plugin.json`));
@@ -94,9 +99,9 @@ export function createLifecycle(definition, checksPermissions = () => true, opti
     let programs;
     let plugin;
     const granted = new Set();
-    let line;
     let activation;
     let mod;
+    let imports;
     let failure;
     let pluginOptions = options;
     const installer = createInstaller(definition.name, () => claude());
@@ -110,18 +115,16 @@ export function createLifecycle(definition, checksPermissions = () => true, opti
             throw new Error(`${definition.name}: the lifecycle has not started. registerMod(addHook, mod, options) starts it at session.start.`);
         return runtime.claude;
     };
-    const showLine = () => {
-        line ??= runtime?.progress.start(`Installing ${definition.name}`);
-        return line;
+    const installing = (description) => runtime?.toaster.toast.loading('Installing', { id: installId, ...(description === undefined ? {} : { description }) });
+    const toastFailure = (shown) => {
+        if (runtime !== undefined)
+            showFailure({ name: definition.name, ui: runtime.toaster, claude: runtime.claude }, shown);
     };
-    const endLine = () => {
-        line?.end();
-        line = undefined;
-    };
-    const fail = (reason, fix) => {
+    const fail = (reason, fix, retry) => {
         phase = 'failed';
         failure ??= new Error(`${definition.name}: ${reason}${/[.!?]$/.test(reason) ? '' : '.'} ${fix}`);
-        showLine().fail(reason, fix);
+        const action = retry === undefined ? {} : { action: { label: 'Retry', onClick: () => ((failure = undefined), retry().catch(report)) } };
+        runtime?.toaster.toast.error(reason, { id: installId, description: fix, duration: Infinity, ...action });
     };
     const finish = async () => {
         await programs?.refresh();
@@ -132,7 +135,7 @@ export function createLifecycle(definition, checksPermissions = () => true, opti
         if (plugin === undefined || (await cmodVersion(claude())) === undefined)
             return;
         const { code, lastError } = await readLines(claude().process.spawn({ argv: ['cmod', 'setup', plugin.root, '--events'] }), (text) => {
-            if (parseEvent(text).kind === 'done')
+            if (parseEvent(text).type === 'done')
                 shouldRecord = false;
         });
         if (shouldRecord)
@@ -149,12 +152,12 @@ export function createLifecycle(definition, checksPermissions = () => true, opti
         const option = definition.options?.[key];
         if (option === undefined || plugin === undefined)
             return `${definition.name} has no option ${key}.`;
-        const value = option.kind === 'number' ? Number(text) : option.kind === 'toggle' ? text.trim() === 'true' : option.kind === 'list' ? text.split(',').map((item) => item.trim()).filter((item) => item !== '') : text;
-        const misfit = option.kind === 'toggle' && !['true', 'false'].includes(text.trim()) ? 'takes true or false' : fitsOption(option, value);
+        const value = option.type === 'number' ? Number(text) : option.type === 'toggle' ? text.trim() === 'true' : option.type === 'list' ? text.split(',').map((item) => item.trim()).filter((item) => item !== '') : text;
+        const misfit = option.type === 'toggle' && !['true', 'false'].includes(text.trim()) ? 'takes true or false' : fitsOption(option, value);
         if (misfit !== undefined)
             return `${option.title} ${misfit}.`;
         const saved = await claude().process.run(['cmod', 'option', plugin.name, key, Array.isArray(value) ? value.join(',') : String(value)]);
-        return saved.exitCode === 0 ? undefined : lastLineOf(saved.stderr) ?? `cmod option exited ${saved.exitCode}.`;
+        return saved.exitCode === 0 ? undefined : cmodError(saved.stderr, 'option') || `cmod option ${formatExit(saved.exitCode, '')}.`;
     };
     const askOptions = async (missing) => {
         if (!asksPerson || plugin === undefined || (await claude().session.surfaces()).length === 0)
@@ -171,21 +174,35 @@ export function createLifecycle(definition, checksPermissions = () => true, opti
         pluginOptions = { ...pluginOptions, ...Object.fromEntries(rows.filter((row) => row.key.startsWith(prefix)).map((row) => [row.key.slice(prefix.length), row.value])) };
         return true;
     };
+    const isStepDone = async (active, step) => {
+        try {
+            return await step.isDone(active);
+        }
+        catch (error) {
+            toastFailure({ id: `step:${step.title}`, message: `The ${step.title} step's isDone failed`, error });
+            return false;
+        }
+    };
     const pendingSteps = async (active) => {
         const pending = [];
         for (const step of definition.installer ?? [])
-            if (!(await Promise.resolve(step.isDone(active)).catch(() => false)))
+            if (!(await isStepDone(active, step)))
                 pending.push(step.title);
         return pending;
     };
     const runSteps = async (active) => {
         const steps = asksPerson ? (definition.installer ?? []) : [];
         for (const [index, step] of steps.entries()) {
-            if (await Promise.resolve(step.isDone(active)).catch(() => false))
+            if (await isStepDone(active, step))
                 continue;
             const isAnswered = (await claude().session.surfaces()).length > 0 && (await installer.step(active, step, index + 1, steps.length));
             if (!isAnswered) {
-                claude().ui.log(`${definition.name} needs ${steps.length - index === 1 ? 'one more step' : `${steps.length - index} more steps`}, starting with ${step.title}. Run /mods ${definition.name} to finish.`);
+                runtime?.toaster.toast.warning(steps.length - index === 1 ? 'Needs one more step' : `Needs ${steps.length - index} more steps`, {
+                    id: 'cmod:steps',
+                    description: `Starting with ${step.title}. Finish them in /mods ${definition.name}.`,
+                    duration: Infinity,
+                    action: { label: 'Finish', onClick: () => active.settings.open() },
+                });
                 break;
             }
         }
@@ -195,7 +212,7 @@ export function createLifecycle(definition, checksPermissions = () => true, opti
         if (runtime === undefined || plugin === undefined)
             return;
         const activeRouter = createRouter();
-        const active = await createMod(definition, { ...runtime, router: activeRouter, dataFolder: dataFolder(plugin.store, plugin.name), steps: plugin.steps, granted, refreshGrants, checksPermissions, options: pluginOptions }).catch(async (error) => {
+        const active = await createMod(definition, { ...runtime, router: activeRouter, dataFolder: dataFolder(plugin.store, plugin.name), store: plugin.store, steps: plugin.steps, granted, refreshGrants, checksPermissions, options: pluginOptions }).catch(async (error) => {
             if (error instanceof MissingOptions && (await askOptions(error)))
                 return undefined;
             fail(messageOf(error), error instanceof MissingOptions ? `Set ${error.keys.length === 1 ? 'it' : 'them'} in /config.` : 'Fix it, then run /reload-plugins.');
@@ -205,48 +222,57 @@ export function createLifecycle(definition, checksPermissions = () => true, opti
             return activate();
         const { added } = active;
         mod = active.mod;
+        imports = active.imports;
         router = activeRouter;
         phase = 'active';
         runtime.claude.ui.invalidate('ui.render');
-        endLine();
-        void runSteps(active.mod).catch((error) => claude().ui.log(`${definition.name}: its installer stopped: ${messageOf(error)}`));
+        void runSteps(active.mod).catch((error) => toastFailure({ id: 'cmod:steps', message: 'Its installer stopped', error }));
         const missed = missedSessionStart;
         missedSessionStart = undefined;
         const lateAnswer = missed === undefined ? {} : await activeRouter.dispatch('classic.SessionStart', missed, async () => ({})).catch((error) => {
-            claude().ui.log(`${definition.name}: the SessionStart hook failed: ${messageOf(error)}`);
+            toastFailure({ id: 'classic.SessionStart', message: 'The SessionStart hook failed', error });
             return {};
         });
         if (Object.keys(lateAnswer).length > 0) {
             runtime.claude.ui.log(`${definition.name} started after Claude Code's SessionStart, so Claude Code did not read the answer of its SessionStart hooks.`, { to: 'debug' });
         }
         const version = plugin.version ?? '';
-        if ((await runtime.claude.store.get(announcedKey)) === version)
+        const announced = announcedOf(await runtime.claude.store.get(announcedKey));
+        if (announced?.version === version) {
+            runtime.toaster.toast.dismiss(installId);
             return;
-        await runtime.claude.store.set(announcedKey, version);
-        runtime.claude.ui.toast(`${definition.name} is ready`);
-        if (added.length > 0)
-            runtime.claude.ui.log(`${definition.name} added ${listed(added)}.`);
+        }
+        await runtime.claude.store.set(announcedKey, { version, added });
+        const { toaster } = runtime;
+        void announcementOf(runtime.claude, plugin, granted, added, announced)
+            .then(({ message, ...options }) => toaster.toast.success(message, { id: installId, duration: announcementMs, ...options }))
+            .catch((error) => toastFailure({ id: installId, message: 'Could not say what it installed', error }));
     };
     const updatesToShow = async () => {
         const [home, configHome] = await Promise.all([claude().env.home(), claude().env.configHome()]);
         const configRoot = configHome ?? `${home ?? ''}/.claude`;
-        const known = await claude().fs.read(`${configRoot}/plugins/known_marketplaces.json`).then((text) => JSON.parse(text), () => undefined);
+        const known = await claude()
+            .fs.read(`${configRoot}/plugins/known_marketplaces.json`)
+            .then((text) => JSON.parse(text))
+            .catch(ifMissing(undefined));
         return updatesToTurnOn(marketplaceOf(claude().plugin.root, claude().plugin.name), await claude().settings.read({ source: 'user' }), known);
     };
     const askConsent = async (event) => {
         const name = definition.name;
         if ((await claude().session.surfaces()).length === 0) {
-            showLine().wait(`Waiting for consent: run cmod install ${name}`);
             claude().ui.log(`${name} waits for consent to run ${event.install}. Run cmod install ${name} in a terminal.`);
             return;
         }
-        showLine().wait('Waiting for your answer');
-        if (await installer.consent({ ...event, updates: await updatesToShow().catch(() => undefined) }))
+        installing('Waiting for your answer');
+        const updates = await updatesToShow().catch((error) => {
+            toastFailure({ id: 'cmod:updates', message: 'Could not read whether its marketplace updates automatically', error });
+            return undefined;
+        });
+        if (await installer.consent({ ...event, updates }))
             return install(event.sha256);
         await installer.close();
         phase = 'declined';
-        endLine();
-        claude().ui.log(`${name} is not installed. Run cmod install ${name} to install it.`);
+        runtime?.toaster.toast('Not installed', { id: installId, description: `Run cmod install ${name} to install it.` });
     };
     const install = async (consent) => {
         if (plugin === undefined)
@@ -257,31 +283,30 @@ export function createLifecycle(definition, checksPermissions = () => true, opti
         const found = await cmodVersion(claude());
         if (!fits(found))
             return waitForcmod(found);
-        endLine();
-        const progress = showLine();
+        installing();
         let outcome;
         const argv = ['cmod', 'setup', plugin.root, '--events', ...(consent === undefined ? [] : ['--consent', consent])];
         const { code, lastError } = await readLines(claude().process.spawn({ argv }), (text) => {
             const event = parseEvent(text);
-            if (event.kind === 'progress')
-                progress.report(event);
-            if (event.kind === 'done' || event.kind === 'failed' || event.kind === 'needs-consent')
+            if (event.type === 'progress')
+                installing(progressOf(event));
+            if (event.type === 'done' || event.type === 'failed' || event.type === 'needs-consent')
                 outcome = event;
         });
-        if (outcome?.kind === 'done') {
+        if (outcome?.type === 'done') {
             for (const item of plugin.steps.permissions ?? [])
                 granted.add(item);
             return finish();
         }
-        if (outcome?.kind === 'needs-consent')
+        if (outcome?.type === 'needs-consent')
             return askConsent(outcome);
-        const reason = outcome?.kind === 'failed' ? outcome.message : `cmod setup ${formatExit(code, lastError)}`;
-        fail(reason, `Fix the cause, then run: cmod install ${definition.name}`);
+        const reason = outcome?.type === 'failed' ? outcome.message : `cmod setup ${formatExit(code, lastError)}`;
+        fail(reason, `Fix the cause, then retry, or run cmod install ${definition.name} in a terminal.`, install);
     };
     const fits = (found) => found !== undefined && isAtLeast(found, oldestCmodFor(plugin?.steps ?? {}));
     const waitForcmod = (found) => {
         phase = 'waiting';
-        showLine().wait('Waiting for cmod');
+        installing('Waiting for cmod');
         let latest = found;
         let check;
         const stop = () => {
@@ -303,21 +328,21 @@ export function createLifecycle(definition, checksPermissions = () => true, opti
                 report(error);
             });
         });
-        const longWait = claude().clock.after(cmodWaitMs, () => showLine().wait(latest === undefined
+        const longWait = claude().clock.after(cmodWaitMs, () => installing(latest === undefined
             ? "Still waiting for cmod to download cmod. See cmod's own line."
             : `PATH finds cmod ${latest}, and ${definition.name} needs cmod ${oldestCmodFor(plugin?.steps ?? {})} or later. Run npm i -g @cmodjs/cli, or put ~/.local/bin ahead of the old cmod on PATH.`));
     };
     const bootstrap = async (root) => {
-        const progress = showLine();
+        installing();
         phase = 'installing';
         const { code, lastError } = await readLines(claude().process.spawn({ argv: ['sh', '-c', './setup/bootstrap.sh'], cwd: root }), (text) => {
             const event = parseEvent(text);
-            if (event.kind === 'progress')
-                progress.report(event);
+            if (event.type === 'progress')
+                installing(progressOf(event));
         });
         if (code === 0)
             return finish();
-        fail(`bootstrap ${formatExit(code, lastError)}`, `Run ./setup/bootstrap.sh in ${root} to see the whole log.`);
+        fail(`bootstrap ${formatExit(code, lastError)}`, `Run ./setup/bootstrap.sh in ${root} to see the whole log.`, () => bootstrap(root));
     };
     const report = (error) => {
         failure = error;
@@ -325,15 +350,33 @@ export function createLifecycle(definition, checksPermissions = () => true, opti
             fail(messageOf(error), `Run cmod install ${definition.name} in a terminal to see the whole log.`);
     };
     let consentMs = 0;
-    const consentStamp = async (path) => {
-        const stat = await claude().fs.stat(path).catch(() => undefined);
+    const stampOf = async (path) => {
+        const stat = await claude().fs.stat(path).catch(ifMissing(undefined));
         return stat?.kind === 'file' ? stat.mtimeMs : 0;
     };
+    let recordMs = 0;
+    let readStarted;
+    const recover = async () => {
+        if (plugin === undefined || readStarted === undefined || (phase !== 'failed' && phase !== 'declined'))
+            return;
+        const modifiedMs = await stampOf(recordPath(plugin.store, plugin.name));
+        if (modifiedMs === recordMs)
+            return;
+        recordMs = modifiedMs;
+        const current = await readStarted(claude());
+        if (!current.isInstalled)
+            return;
+        plugin = current;
+        failure = undefined;
+        activation = undefined;
+        await refreshGrants();
+        await finish();
+    };
     const refreshGrants = async () => {
         if (plugin === undefined || plugin.name === cmodPluginName)
             return;
         const path = consentPath(plugin.store);
-        const modifiedMs = await consentStamp(path);
+        const modifiedMs = await stampOf(path);
         if (modifiedMs === consentMs)
             return;
         consentMs = modifiedMs;
@@ -356,7 +399,7 @@ export function createLifecycle(definition, checksPermissions = () => true, opti
             droppedParts.add(item);
             const declared = plugin?.steps.permissions ?? [];
             const fix = declared.includes(item) ? `Turn it on in /mods ${definition.name}.` : `It needs "permissions": { "${item}": true } in package.json "cmod".`;
-            claude().ui.log(`${definition.name} answered ${part} without your grant to "${permissionWords(item)}", so cmod dropped it. ${fix}`);
+            runtime?.toaster.toast.warning(`Answered ${part} without your grant to "${permissionWords(item)}", so cmod dropped it`, { id: `dropped:${item}`, description: fix, duration: Infinity });
         },
     };
     const checkedRoute = async (event, e, next) => {
@@ -371,13 +414,15 @@ export function createLifecycle(definition, checksPermissions = () => true, opti
         if (activation !== undefined && phase !== 'active')
             await activation;
     };
-    const holdSessionStart = () => new Promise((resolve) => {
-        const limit = claude().clock.after(sessionStartHoldMs, resolve);
-        void startSettled.then(whenActive).then(() => {
-            limit.cancel();
-            resolve();
+    const holdUntilStarted = () => runtime === undefined
+        ? startSettled.then(whenActive)
+        : new Promise((resolve) => {
+            const limit = claude().clock.after(startHoldMs, resolve);
+            void startSettled.then(whenActive).then(() => {
+                limit.cancel();
+                resolve();
+            });
         });
-    });
     return {
         get phase() {
             return phase;
@@ -388,11 +433,14 @@ export function createLifecycle(definition, checksPermissions = () => true, opti
         get failure() {
             return failure;
         },
+        get toasts() {
+            return runtime?.toaster.shown ?? [];
+        },
         async start(claudeCalls, read) {
             if (runtime !== undefined)
                 return;
             programs = locatingPrograms(claudeCalls);
-            runtime = { claude: programs.claude, progress: createProgress(claudeCalls) };
+            runtime = { claude: programs.claude, toaster: createToaster(claudeCalls, definition.name) };
             try {
                 await programs.refresh();
                 const started = await read(claudeCalls).catch((error) => {
@@ -402,9 +450,11 @@ export function createLifecycle(definition, checksPermissions = () => true, opti
                 if (started === undefined)
                     return;
                 plugin = started;
+                readStarted = read;
                 for (const item of started.granted)
                     granted.add(item);
-                consentMs = await consentStamp(consentPath(started.store));
+                consentMs = await stampOf(consentPath(started.store));
+                recordMs = await stampOf(recordPath(started.store, started.name));
                 if (started.isInstalled) {
                     shouldRecord = started.shouldRecord;
                     if (shouldRecord)
@@ -420,6 +470,8 @@ export function createLifecycle(definition, checksPermissions = () => true, opti
             }
         },
         async route(event, e, next) {
+            if (imports !== undefined)
+                bind(imports);
             if (event === 'ui.render' && installer.draws(e))
                 return installer.draw(e);
             if (event === 'ui.close')
@@ -432,10 +484,13 @@ export function createLifecycle(definition, checksPermissions = () => true, opti
             }
             if (shouldRecord && event === 'classic.UserPromptSubmit')
                 record();
-            await (event === 'classic.SessionStart' ? holdSessionStart() : whenActive());
+            if (event === 'classic.UserPromptSubmit' || event === 'classic.SessionStart')
+                await recover().catch((error) => claude().ui.log(`${definition.name} stays stopped: ${messageOf(error)}`, { to: 'debug' }));
+            const isCallToThisMod = event === 'cmod.call' && e.to === definition.name;
+            await (event === 'classic.SessionStart' || isCallToThisMod ? holdUntilStarted() : whenActive());
             if (event === 'classic.SessionStart' && phase !== 'active')
                 missedSessionStart = e;
-            if (event === 'cmod.call' && phase !== 'active' && e.to === definition.name) {
+            if (isCallToThisMod && phase !== 'active') {
                 const isStopped = phase === 'declined' || phase === 'failed';
                 return { deny: isStopped ? notInstalled(definition.name) : `${definition.name} is installing. Try again when it's ready.` };
             }
@@ -452,17 +507,18 @@ export function createLifecycle(definition, checksPermissions = () => true, opti
                 return checkedRoute(event, e, next);
             const answer = router.dispatch(event, e, next);
             const render = e;
-            if (event !== 'ui.render' || render.component !== 'AbovePrompt' || runtime === undefined || !runtime.progress.isShown)
+            if (event !== 'ui.render' || render.component !== 'AbovePrompt' || runtime === undefined)
                 return answer;
-            return runtime.progress.draw((await answer), runtime.claude.ui.resolve(render), render.viewport?.columns);
+            return runtime.toaster.draw((await answer), runtime.claude.ui.resolve(render), render.props);
         },
     };
 }
 async function createMod(definition, runtime) {
-    const { router, progress } = runtime;
-    const claude = checkingKeys(runtime.claude, definition.name, runtime.steps.keys ?? {});
+    const { router, toaster } = runtime;
+    const report = (failure) => void showFailure({ name: definition.name, ui: toaster, claude: runtime.claude }, failure);
+    const claude = withBareRefusals(checkingKeys(runtime.claude, toaster.toast, runtime.steps.keys ?? {}));
     const added = [];
-    const hookEvents = [];
+    const hooksAdded = [];
     const announce = (feature) => {
         added.push(feature);
     };
@@ -478,19 +534,24 @@ async function createMod(definition, runtime) {
         configRoot,
         projectRoot: () => modState.root,
         freeFolders: () => [modState.root, runtime.dataFolder],
+        freeAddresses: () => programAddresses(mod),
     };
     const checked = checkingGrants(claude, grants);
+    const places = { home, configRoot, projectRoot: () => modState.root };
     const files = createModFiles({
         name: definition.name,
         claude,
-        places: { home, configRoot, projectRoot: () => modState.root },
+        places,
         checkWrite: (path) => checkWrite(grants, `metadata.update(${path})`, path),
+        report,
     });
     const pages = new Map();
     const settingsPages = {
         page(page) {
             if (pages.has(page.id))
                 throw new Error(`${definition.name}: the settings page "${page.id}" is already added. Give each page its own id.`);
+            if (page.id === changelogPage)
+                throw new Error(`${definition.name}: the settings page id "${changelogPage}" opens the mod's CHANGELOG.md in /mods. Give the page another id.`);
             pages.set(page.id, { title: page.title, handle: area.ui.pane(page) });
         },
         async open(pageId) {
@@ -507,87 +568,147 @@ async function createMod(definition, runtime) {
     let cwd = startCwd;
     let loadedCwd = startCwd;
     let staleCwd;
-    const area = createUi({ name: definition.name, claude, router, progress, announce, mod: () => mod });
-    const modState = createState({ name: definition.name, initial: definition.state ?? {}, session, root, claude, changed: area.changed });
-    const modOptions = createOptions({ name: definition.name, declared: definition.options ?? {}, fromClaude: runtime.options, claude, changed: modState.changed });
+    let forkedFrom;
+    let parentAsked;
+    let hasEarlierPrompts = true;
+    const area = createUi({ name: definition.name, claude, router, toaster, report, announce, mod: () => mod });
+    const askParent = async () => {
+        if (definition.name === cmodPluginName)
+            return undefined;
+        try {
+            const parent = await claude.cmod.call({ to: cmodPluginName, method: 'forkParent', input: null });
+            return typeof parent === 'string' ? parent : undefined;
+        }
+        catch (error) {
+            claude.ui.log(`${definition.name} starts without the session values of the conversation it was forked from: ${messageOf(error)}`, { to: 'debug' });
+            return undefined;
+        }
+    };
+    const forkParent = () => (parentAsked ??= askParent().then((parent) => {
+        forkedFrom = parent;
+        return parent;
+    }));
+    const modState = createState({ name: definition.name, initial: definition.state ?? {}, session, root, claude, report, changed: area.changed, forkParent });
+    const modOptions = createOptions({ name: definition.name, declared: definition.options ?? {}, fromClaude: runtime.options, claude, report, changed: modState.changed });
     const held = runtime.checksPermissions() ? new Map() : undefined;
-    const mod = {
-        name: definition.name,
-        state: modState.state,
-        get options() {
-            return modOptions.values;
-        },
-        dataFolder: runtime.dataFolder,
-        on(event, hook, options) {
-            const bounded = options?.timeoutMs === undefined ? hook : timedHook(definition.name, event, hook, checkedMs(definition.name, `the ${event} hook's timeoutMs`, options.timeoutMs), claude);
-            if (!hookEvents.includes(event))
-                hookEvents.push(event);
-            if (event === 'PreToolUse')
-                router.add('tool.call', preToolUseHook(definition.name, bounded, claude, agents, held));
-            else
-                router.add(`classic.${event}`, classicHook(definition.name, event, bounded, claude, agents));
-        },
-        use: (job) => job({ mod, announce, reserveName, toolCalls: agents }),
-        every(ms, hook) {
-            let isRunning = false;
-            return claude.clock.every(checkedMs(definition.name, 'mod.every', ms), () => {
-                if (isRunning)
-                    return;
-                isRunning = true;
-                void Promise.resolve()
-                    .then(hook)
-                    .catch((error) => claude.ui.log(`${definition.name}: the every ${ms} ms hook failed: ${messageOf(error)}`))
-                    .finally(() => {
-                    isRunning = false;
-                });
-            });
-        },
-        ui: area.ui,
-        process: {
-            run: (argv, init) => checked.process.run(argv, init),
-            spawn: (argv, init) => checked.process.spawn({ ...init, argv }),
+    const expand = (path) => (path === '~' || path.startsWith('~/') ? resolvedPath(path, places) : path);
+    const settingsFile = (source) => ({
+        read: () => checked.settings.read({ source }),
+        async update(values) {
+            await checkSettings(grants, source, Object.keys(values));
+            await claude.cmod.call({ to: cmodPluginName, method: 'updateSettings', input: { mod: definition.name, source, project: modState.root, values } });
         },
+    });
+    const client = createSessionsClient({ name: definition.name, claude: checked, report: (id, message, error) => report({ id, message, error }) });
+    let followed;
+    const followFolders = (project, folder) => {
+        if (followed === undefined)
+            return;
+        followed = { ...followed, project, cwd: folder };
+        client.follow(followed);
+    };
+    const imports = {
+        sessions: client.sessions,
+        settings: { user: settingsFile('user'), project: settingsFile('project'), local: settingsFile('local') },
+        model: { complete: (completion, options) => checked.model.complete(completion, options) },
         fs: {
-            read: (path) => checked.fs.read(path),
-            write: (path, text) => checked.fs.write(path, text),
-            list: (path) => checked.fs.list(path),
-            exists: (path) => checked.fs.exists(path),
-            stat: (path, options) => checked.fs.stat(path, options),
+            read: (path) => checked.fs.read(expand(path)),
+            write: (path, text) => checked.fs.write(expand(path), text),
+            exists: (path) => checked.fs.exists(expand(path)),
             find: (glob) => files.find(glob),
+            list: async (path) => (await checked.fs.list(path === undefined ? undefined : expand(path))).map(({ name, kind, size, mtimeMs, isLink }) => ({ name, isFile: kind === 'file', isFolder: kind === 'dir', isLink, size, modifiedAt: mtimeMs })),
+            async stat(path, options) {
+                const { kind, size, mtimeMs, isLink, realPath } = await checked.fs.stat(expand(path), options);
+                return { isFile: kind === 'file', isFolder: kind === 'dir', isLink, size, modifiedAt: mtimeMs, ...(realPath === undefined ? {} : { realPath }) };
+            },
         },
         metadata: {
             read: (path) => files.read(path),
             update: (path, change) => files.update(path, change),
         },
+        process: {
+            run: (argv, init) => checked.process.run(argv, init),
+            spawn: (argv, init) => checked.process.spawn({ ...init, argv }),
+        },
         http: { fetch: (url, init) => checked.http.fetch(url, init) },
-        settings: settingsPages,
-        session: {
-            messages: ((args) => (args === undefined ? checked.session.messages() : checked.session.messages({ agentId: args.agentId }))),
-            async append(text) {
-                const added = await checked.session.append({ message: { type: 'user', content: [{ type: 'text', text }] } });
-                if (added.deny !== undefined)
-                    throw new Error(`${definition.name}: Claude Code refused the note: ${added.deny}`);
-            },
-            async submit(text) {
-                const submitted = await checked.prompt.submit({ text });
-                if ('drop' in submitted && typeof submitted.drop === 'string')
-                    throw new Error(`${definition.name}: Claude Code dropped the prompt: ${submitted.drop}`);
-            },
+    };
+    const allowed = (permission) => ({ allows: (value) => isCovered(granted, itemOf(permission, value), home) });
+    const flag = (permission) => isCovered(granted, permission, home);
+    const timer = (ms, subject, start, listener) => {
+        let isRunning = false;
+        const started = start(checkedMs(definition.name, `mod.${subject}`, ms), () => {
+            if (isRunning)
+                return;
+            isRunning = true;
+            void Promise.resolve()
+                .then(() => {
+                bind(imports);
+                return listener();
+            })
+                .catch((error) => report({ id: `${subject}:${ms}`, message: `The ${subject} ${ms} ms timer failed`, error }))
+                .finally(() => {
+                isRunning = false;
+            });
+        });
+        return { dispose: () => started.cancel() };
+    };
+    const mod = {
+        name: definition.name,
+        folder: claude.plugin.root,
+        dataFolder: runtime.dataFolder,
+        state: modState.state,
+        get options() {
+            return modOptions.values;
         },
-        agent: { spawn: (args) => checked.agent.spawn(args) },
-        model: { complete: (completion, options) => checked.model.complete(completion, options) },
         permissions: {
-            has: (name, value) => isCovered(granted, itemOf(name, value), home),
-        },
-        claude: { ...checked, on: (event, hook) => router.add(event, hook) },
-        get projectRoot() {
-            return modState.root;
+            get conversation() {
+                return flag('conversation');
+            },
+            get prompt() {
+                return flag('prompt');
+            },
+            get model() {
+                return flag('model');
+            },
+            get tasks() {
+                return flag('tasks');
+            },
+            get tools() {
+                return flag('tools');
+            },
+            get approve() {
+                return flag('approve');
+            },
+            network: allowed('network'),
+            run: allowed('run'),
+            files: allowed('files'),
+            config: allowed('config'),
         },
-        get cwd() {
-            return cwd;
+        on(hook, matcherOrListener, listenerOrOptions, maybeOptions) {
+            const hasMatcher = typeof listenerOrOptions === 'function';
+            const listener = (hasMatcher ? listenerOrOptions : matcherOrListener);
+            const matcher = hasMatcher ? matcherOrListener : undefined;
+            const options = (hasMatcher ? maybeOptions : listenerOrOptions);
+            if (!hooks.includes(hook))
+                throw new Error(`${definition.name}: mod.on takes one of Claude Code's hooks, such as PreToolUse, not ${String(hook)}.`);
+            const matched = matcher === undefined ? listener : (input) => (matches(input, matcher) ? listener(input) : undefined);
+            const bounded = options?.timeoutMs === undefined ? matched : timedHook(hook, matched, checkedMs(definition.name, `the ${hook} hook's timeoutMs`, options.timeoutMs), claude, toaster.toast);
+            if (!hooksAdded.includes(hook))
+                hooksAdded.push(hook);
+            if (hook === PreToolUse)
+                return router.add('tool.call', preToolUseHook(definition.name, bounded, claude, agents, held));
+            const classic = hook;
+            return router.add(`classic.${classic}`, classicHook(definition.name, classic, bounded, claude, agents, report));
         },
+        every: (ms, listener) => timer(ms, 'every', claude.clock.every, listener),
+        after: (ms, listener) => timer(ms, 'after', claude.clock.after, listener),
+        use: (job) => job({ mod, announce, reserveName }),
+        log: (text) => claude.ui.log(`${definition.name}: ${text}`, { to: 'debug' }),
+        ui: { ...area.ui, notice: (callId, text) => claude.ui.notice(callId, text) },
+        settings: settingsPages,
         dependencies: dependencyCalls(claude, (call, task) => beforeDeadline(claude, { ms: dependencyCallMs }, call, task)),
     };
+    bind(imports);
     const followSession = async (isAfterCd = false) => {
         try {
             const [nextRoot, reportedCwd] = await Promise.all([claude.session.root(), claude.session.cwd()]);
@@ -601,9 +722,11 @@ async function createMod(definition, runtime) {
             if (!hasMovedRoot && nextCwd === oldCwd)
                 return;
             cwd = nextCwd;
+            followFolders(nextRoot, nextCwd);
             await modState.moveTo(nextRoot).catch((error) => {
                 if (cwd === nextCwd)
                     cwd = loadedCwd;
+                followFolders(modState.root, cwd);
                 throw error;
             });
             if (hasMovedRoot)
@@ -617,18 +740,34 @@ async function createMod(definition, runtime) {
             await router.dispatch('classic.CwdChanged', moved, async () => ({}));
         }
         catch (error) {
-            claude.ui.log(`${definition.name} keeps the state of ${modState.root} until the next prompt or folder move: ${messageOf(error)}`);
+            report({ id: 'cmod:follow', message: `Keeps the state of ${modState.root} until the next prompt or folder move`, error });
         }
     };
+    const followCurrent = async (title) => {
+        const [id, model, usage] = await Promise.all([claude.session.id(), claude.session.model(), claude.session.usage()]);
+        followed = { id, title: title ?? '', project: modState.root, cwd, model, startedAt: new Date(usage.startedAt).toISOString(), ...(forkedFrom === undefined ? {} : { forkedFrom }) };
+        client.follow(followed);
+    };
     router.add('classic.SessionStart', async (e, next) => {
-        await modState.switchSession(e.session_id, e.source).catch((error) => {
-            claude.ui.log(`${definition.name} kept its session values from before the ${e.source}: ${messageOf(error)}`);
+        const previous = followed?.id;
+        if (e.source === 'fork' && previous !== undefined && previous !== e.session_id)
+            forkedFrom = previous;
+        else if (e.session_id !== previous) {
+            forkedFrom = undefined;
+            parentAsked = undefined;
+        }
+        hasEarlierPrompts = e.source !== 'startup' && e.source !== 'clear';
+        await modState.switchSession(e.session_id, e.source, e.transcript_path).catch((error) => {
+            report({ id: 'cmod:session', message: `Kept its session values from before the ${e.source}`, error });
         });
+        await followCurrent(e.session_title).catch((error) => report({ id: 'cmod:current', message: 'Kept the details of the session from before', error }));
         return next(e);
     });
     router.add('classic.UserPromptSubmit', async (e, next) => {
         staleCwd = undefined;
         await followSession();
+        const isPerson = e.source === undefined || e.source === 'user' || e.source === 'sdk';
+        await followCurrent(e.session_title || (isPerson && !hasEarlierPrompts && client.sessions.current.title === '' ? firstLine(e.prompt) : undefined)).catch((error) => report({ id: 'cmod:current', message: 'Kept the details of the session from before', error }));
         return next(e);
     });
     for (const event of ['classic.PostToolUse', 'classic.PostToolUseFailure']) {
@@ -646,50 +785,63 @@ async function createMod(definition, runtime) {
     });
     router.add('skill.prompt', userSkillHook(claude));
     const api = Object.fromEntries(Object.entries(definition.api ?? {}).map(([method, run]) => [method, (input) => run(input, mod)]));
+    const conversations = definition.name === cmodPluginName ? serveConversations({ claude, router, store: runtime.store, project: () => modState.root, report: (id, message, error) => report({ id, message, error }) }) : undefined;
     router.add('cmod.call', async (e, next) => {
         if (e.to !== definition.name)
             return next(e);
+        const call = e;
+        if (e.method === conversationMethods.changed && call.caller === cmodPluginName) {
+            if (!flag('conversation'))
+                return { value: null };
+            const { session: changedSession, change } = e.input;
+            client.changed(changedSession, change);
+            return { value: null };
+        }
         if (e.method === settingsPagesMethod)
             return { value: [...pages].map(([id, { title }]) => ({ id, title })) };
         if (e.method === openPageMethod) {
             await settingsPages.open(String(e.input));
             return { value: null };
         }
-        return answerCall(definition.name, api, e);
+        const served = await conversations?.answer(call);
+        return served ?? answerCall(definition.name, api, e);
     });
     const agents = toolCalls(claude, router);
+    keepEngine(mod, { claude: checked, router, toolCalls: agents, report });
     const names = new Set();
-    const reserveName = (kind, name, taken) => {
-        const key = `${kind}:${name}`;
+    const reserveName = (type, name, taken) => {
+        const key = `${type}:${name}`;
         if (names.has(key))
             throw new Error(taken);
         names.add(key);
+        return { dispose: () => void names.delete(key) };
     };
     await failsAs('its state did not load', () => modState.load());
     await failsAs('its options did not load', () => modOptions.load(root));
     const missing = modOptions.missing;
     if (missing.length > 0)
         throw new MissingOptions(missing, missing.map((key) => definition.options?.[key]?.title ?? key));
+    await failsAs('the details of its session did not load', () => followCurrent(undefined));
     await failsAs('its setup function threw', () => definition.setup(mod));
     const permissionHooks = permissionEvents.filter((event) => router.has(event));
     if (permissionHooks.length > 0 && !runtime.checksPermissions()) {
         throw new Error(`it decides permissions on ${listed(permissionHooks)}, so hooks/register.ts must call registerPermissionCheck(addHook) after registerMod`);
     }
-    if (held !== undefined && hookEvents.includes('PreToolUse'))
+    if (held !== undefined && hooksAdded.includes(PreToolUse))
         router.add('tool.check', heldDecisionHook(held));
     await failsAs('its open panes did not load', () => area.restorePanes());
-    if (hookEvents.length > 0)
-        added.push(`${hookEvents.length === 1 ? 'a hook' : 'hooks'} on ${listed(hookEvents)}`);
-    return { mod, added };
+    if (hooksAdded.length > 0)
+        added.push(`${hooksAdded.length === 1 ? 'a hook' : 'hooks'} on ${listed(hooksAdded)}`);
+    return { mod, added, imports };
 }
-function checkingKeys(claude, name, keys) {
+function checkingKeys(claude, toast, keys) {
     const bound = Object.entries(keys);
     if (bound.length === 0)
         return claude;
     const register = (command) => {
         for (const [key, commandName] of bound) {
             if (commandName === command.name && command.immediate !== true) {
-                claude.ui.log(`${name}: ${key} runs /${command.name}, which waits for Claude's turn to end and adds a row to the conversation. Give /${command.name} immediate: true.`);
+                toast.warning(`${key} runs /${command.name}, which waits for Claude's turn to end`, { id: `key:${key}`, description: `It adds a row to the conversation. Give /${command.name} immediate: true.`, duration: Infinity });
             }
         }
         return claude.command.register(command);
@@ -702,10 +854,10 @@ function checkedMs(name, subject, ms) {
         throw new Error(`${name}: ${subject} is ${ms}. Give a whole number of milliseconds above 0 and at most ${longestTimerMs}.`);
     return ms;
 }
-function timedHook(name, event, hook, ms, claude) {
+function timedHook(event, hook, ms, claude, toast) {
     return (input) => new Promise((resolve, reject) => {
         const timer = claude.clock.after(ms, () => {
-            claude.ui.log(`${name}: the ${event} hook passed its ${ms / 1000} s timeout`);
+            toast.warning(`The ${event} hook passed its ${ms / 1000} s timeout`, { id: `timeout:${event}` });
             resolve(undefined);
         });
         Promise.resolve()
@@ -727,27 +879,6 @@ async function failsAs(subject, step) {
         throw new Error(`${subject}: ${messageOf(error)}`, { cause: error });
     }
 }
-async function readLines(stream, onLine) {
-    let pending = '';
-    let lastError = '';
-    let piece = await stream.next();
-    while (piece.done !== true) {
-        if (piece.value.stream === 'stderr') {
-            lastError = lastLineOf(piece.value.text) ?? lastError;
-        }
-        else {
-            const lines = `${pending}${piece.value.text}`.split('\n');
-            pending = lines.pop() ?? '';
-            for (const text of lines)
-                onLine(text);
-        }
-        piece = await stream.next();
-    }
-    if (pending !== '')
-        onLine(pending);
-    return { code: piece.value.code, lastError };
-}
-function lastLineOf(text) {
-    const trimmed = text.trim();
-    return trimmed === '' ? undefined : trimmed.slice(trimmed.lastIndexOf('\n') + 1).trim();
+function progressOf({ done, total, label }) {
+    return Box({ gap: 2, children: [Progress({ value: total > 0 ? (done / total) * 100 : 0 }), Text({ dimColor: true, wrap: 'truncate-end', children: label })] });
 }