@cmodjs/core 1.5.1 → 2.0.0

package/runtime/grants.js

@@ -1,4 +1,4 @@
-import { isObject, permissionWords } from '../records.js';
+import { isObject, isSettingCovered, permissionWords, settingPaths } from '../records.js';
 import { relativePath } from '../utils/paths.js';
 import { cmodPluginName } from './dependencies.js';
 import { actPermission, conversationMethods, isAct, toolPermission } from './sessions.js';
@@ -34,9 +34,9 @@ export async function checkGrant(grants, call, item) {
 export async function checkWrite(grants, call, path) {
     await checkGrant(grants, call, writeItem(grants, path));
 }
-export async function checkSettings(grants, source, keys) {
-    for (const key of keys)
-        await checkGrant(grants, `settings.${source}.update(${key})`, `config:${key}`);
+export async function checkSettings(grants, source, values) {
+    for (const path of settingPaths(values).map((each) => each.join('.')))
+        await checkGrant(grants, `settings.${source}.update(${path})`, `config:${path}`);
 }
 export function checkingGrants(claude, grants) {
     const gate = (call, item) => checkGrant(grants, call, item);
@@ -72,10 +72,6 @@ export function checkingGrants(claude, grants) {
         },
         session: {
             ...claude.session,
-            messages: (async (...args) => {
-                await gate('session.messages', 'conversation');
-                return claude.session.messages(...args);
-            }),
             append: async (args) => {
                 await gate('send', 'prompt');
                 return claude.session.append(args);
@@ -91,13 +87,24 @@ export function checkingGrants(claude, grants) {
                 return claude.prompt.submit(args);
             },
         },
+        command: {
+            ...claude.command,
+            run: async (args) => {
+                await gate(`commands.run(${args.command})`, 'prompt');
+                return claude.command.run(args);
+            },
+        },
         cmod: {
             async call(args) {
                 const named = args.to === cmodPluginName ? conversationCalls[args.method] : undefined;
                 const given = args.method === conversationMethods.act && isObject(args.input) ? String(args.input['action']) : undefined;
                 const action = given !== undefined && isAct(given) ? given : undefined;
-                if (named !== undefined)
-                    await gate(action ?? named, action === undefined ? 'conversation' : actPermission(action, isObject(args.input) ? args.input['input'] : undefined));
+                const isThisSession = isObject(args.input) && args.input['session'] === (await claude.session.id());
+                const isDropping = (args.method === conversationMethods.subscribe || args.method === conversationMethods.watchBefore) && isObject(args.input) && Array.isArray(args.input['subscriptions']) && args.input['subscriptions'].length === 0;
+                if (named !== undefined && action !== undefined)
+                    await gate(action, actPermission(action, isObject(args.input) ? args.input['input'] : undefined));
+                else if (named !== undefined && !isThisSession && !isDropping)
+                    await gate(named, 'conversation');
                 return claude.cmod.call(args);
             },
         },
@@ -147,6 +154,8 @@ export function isCovered(granted, item, home) {
     if (split === -1)
         return false;
     const name = item.slice(0, split);
+    if (name === 'config')
+        return isSettingCovered(granted, item.slice(split + 1));
     const target = expanded(item.slice(split + 1), home);
     const values = [...granted].filter((each) => each.startsWith(`${name}:`)).map((each) => expanded(each.slice(name.length + 1), home));
     if (name === 'run')
@@ -189,10 +198,8 @@ function declaration(item, home) {
 const classicParts = {
     additionalContext: 'prompt',
     initialUserMessage: 'prompt',
-    suppressOriginalPrompt: 'prompt',
     updatedToolOutput: 'prompt',
     updatedMCPToolOutput: 'prompt',
-    updatedInput: 'tools',
     retry: 'approve',
 };
 const blocksKeepWorking = ['classic.Stop', 'classic.PostToolUse'];

package/runtime/hooks.d.ts

@@ -1,19 +1,36 @@
-import type { Hook, HookListener } from '../mod.js';
+import type { ClassicHookEvent, ClassicHookInputs, PermissionRequestDecision } from 'claude-code';
 import type { Claude } from './claude.js';
 import type { RoutedHook } from './router.js';
 import type { Failure } from './toaster.js';
-import { type ToolCalls } from './tool-calls.js';
-export type RoutedEvent = `classic.${Exclude<Hook, 'PreToolUse'>}` | 'tool.check' | 'tool.call' | 'prompt.submit' | 'prompt.context' | 'prompt.attachment' | 'command.run' | 'session.measure' | 'skill.prompt' | 'ui.render' | 'ui.press' | 'ui.scroll' | 'ui.close' | 'cmod.call' | 'session.append' | 'session.compact' | 'session.receive' | 'agent.spawn';
+import { type CallBase } from '../utils/call-effects.js';
+export type Hook = Exclude<ClassicHookEvent, 'PreToolUse'>;
+export type HookAnswer = {
+    decision?: 'block';
+    reason?: string;
+    hookSpecificOutput?: {
+        hookEventName?: Hook;
+        additionalContext?: string;
+        permissionDecision?: 'deny' | 'ask';
+        permissionDecisionReason?: string;
+        sessionTitle?: string;
+        initialUserMessage?: string;
+        watchPaths?: string[];
+        reloadSkills?: boolean;
+        decision?: PermissionRequestDecision;
+        retry?: boolean;
+        displayContent?: string;
+        worktreePath?: string;
+    };
+};
+export type HookListener<H extends Hook> = (input: ClassicHookInputs[H]) => HookAnswer | void | Promise<HookAnswer | void>;
+export type RoutedEvent = `classic.${Hook}` | 'tool.check' | 'tool.call' | 'prompt.submit' | 'prompt.context' | 'prompt.attachment' | 'command.run' | 'session.measure' | 'skill.prompt' | 'ui.render' | 'ui.press' | 'ui.scroll' | 'ui.close' | 'cmod.call' | 'session.append' | 'session.compact' | 'session.receive' | 'agent.spawn' | 'turn.start';
 export declare const permissionEvents: readonly RoutedEvent[];
-export declare function classicHook<E extends Exclude<Hook, 'PreToolUse'>>(name: string, event: E, hook: HookListener<E>, claude: Claude, calls: ToolCalls, report: (failure: Failure) => void): RoutedHook<RoutedEvent>;
-type HeldDecision = {
-    readonly decision: 'allow' | 'ask';
-    readonly reason?: string;
+type CallFiles = {
+    readonly read: string[];
+    readonly changed: string[];
 };
-export type HeldDecisions = Map<string, HeldDecision>;
-export declare function preToolUseHook(name: string, hook: HookListener<'PreToolUse'>, claude: Claude, calls: ToolCalls, held: HeldDecisions | undefined): RoutedHook<'tool.call'>;
-export declare function heldDecisionHook(held: HeldDecisions): RoutedHook<'tool.check'>;
+export declare function classicHook<H extends Hook>(name: string, event: H, hook: HookListener<H>, report: (failure: Failure) => void): RoutedHook<RoutedEvent>;
 export declare function userSkillHook(claude: Claude): RoutedHook<'skill.prompt'>;
-export declare const strictness: readonly ['allow', 'ask', 'deny'];
+export declare function callFiles(name: string, claude: Claude, use: CallBase, cwd: string): Promise<CallFiles>;
 export {};
 //# sourceMappingURL=hooks.d.ts.map

package/runtime/hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/runtime/hooks.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAyB,YAAY,EAAE,MAAM,WAAW,CAAA;AAE1E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAC3C,OAAO,EAA6B,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAM3E,MAAM,MAAM,WAAW,GACnB,WAAW,OAAO,CAAC,IAAI,EAAE,YAAY,CAAC,EAAE,GACxC,YAAY,GACZ,WAAW,GACX,eAAe,GACf,gBAAgB,GAChB,mBAAmB,GACnB,aAAa,GACb,iBAAiB,GACjB,cAAc,GACd,WAAW,GACX,UAAU,GACV,WAAW,GACX,UAAU,GACV,WAAW,GACX,gBAAgB,GAChB,iBAAiB,GACjB,iBAAiB,GACjB,aAAa,CAAA;AAEjB,eAAO,MAAM,gBAAgB,EAAE,SAAS,WAAW,EAAgD,CAAA;AA4CnG,wBAAgB,WAAW,CAAC,CAAC,SAAS,OAAO,CAAC,IAAI,EAAE,YAAY,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,UAAU,CAAC,WAAW,CAAC,CAuB/M;AAED,KAAK,YAAY,GAAG;IAAE,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAEpF,MAAM,MAAM,aAAa,GAAG,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;AAErD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,aAAa,GAAG,SAAS,GAAG,UAAU,CAAC,WAAW,CAAC,CA6BzK;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,aAAa,GAAG,UAAU,CAAC,YAAY,CAAC,CAM9E;AAYD,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAAC,cAAc,CAAC,CAexE;AAgED,eAAO,MAAM,UAAU,YAAI,OAAO,EAAE,KAAK,EAAE,MAAM,CAAU,CAAA"}
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/runtime/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAA;AAEjG,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAC3C,OAAO,EAAe,KAAK,QAAQ,EAAmB,MAAM,0BAA0B,CAAA;AAKtF,MAAM,MAAM,IAAI,GAAG,OAAO,CAAC,gBAAgB,EAAE,YAAY,CAAC,CAAA;AAE1D,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,kBAAkB,CAAC,EAAE;QACnB,aAAa,CAAC,EAAE,IAAI,CAAA;QACpB,iBAAiB,CAAC,EAAE,MAAM,CAAA;QAC1B,kBAAkB,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;QACnC,wBAAwB,CAAC,EAAE,MAAM,CAAA;QACjC,YAAY,CAAC,EAAE,MAAM,CAAA;QACrB,kBAAkB,CAAC,EAAE,MAAM,CAAA;QAC3B,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;QACrB,YAAY,CAAC,EAAE,OAAO,CAAA;QACtB,QAAQ,CAAC,EAAE,yBAAyB,CAAA;QACpC,KAAK,CAAC,EAAE,OAAO,CAAA;QACf,cAAc,CAAC,EAAE,MAAM,CAAA;QACvB,YAAY,CAAC,EAAE,MAAM,CAAA;KACtB,CAAA;CACF,CAAA;AAED,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,IAAI,IAAI,CAAC,KAAK,EAAE,iBAAiB,CAAC,CAAC,CAAC,KAAK,UAAU,GAAG,IAAI,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAA;AAE1H,MAAM,MAAM,WAAW,GACnB,WAAW,IAAI,EAAE,GACjB,YAAY,GACZ,WAAW,GACX,eAAe,GACf,gBAAgB,GAChB,mBAAmB,GACnB,aAAa,GACb,iBAAiB,GACjB,cAAc,GACd,WAAW,GACX,UAAU,GACV,WAAW,GACX,UAAU,GACV,WAAW,GACX,gBAAgB,GAChB,iBAAiB,GACjB,iBAAiB,GACjB,aAAa,GACb,YAAY,CAAA;AAEhB,eAAO,MAAM,gBAAgB,EAAE,SAAS,WAAW,EAAgD,CAAA;AAInG,KAAK,SAAS,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAA;AAuCxE,wBAAgB,WAAW,CAAC,CAAC,SAAS,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,UAAU,CAAC,WAAW,CAAC,CAgBtJ;AAMD,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAAC,cAAc,CAAC,CAexE;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAgB5G"}

package/runtime/hooks.js

@@ -1,26 +1,24 @@
 import { configFolders } from '../records.js';
-import { reservedKeys, toolInputOf } from './tool-calls.js';
-import { callEffects, inputOf } from '../utils/call-effects.js';
+import { callEffects } 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 const permissionEvents = ['tool.check', 'classic.PermissionRequest'];
-const flags = ['suppressOriginalPrompt', 'reloadSkills', 'retry'];
+const flags = ['reloadSkills', 'retry'];
 const readFields = {
     Setup: ['additionalContext'],
     SessionStart: ['additionalContext', 'initialUserMessage', 'sessionTitle', 'watchPaths', 'reloadSkills'],
     SessionEnd: [],
-    UserPromptSubmit: ['additionalContext', 'sessionTitle', 'suppressOriginalPrompt'],
-    UserPromptExpansion: ['additionalContext', 'suppressOriginalPrompt'],
+    UserPromptSubmit: ['additionalContext', 'sessionTitle'],
+    UserPromptExpansion: ['additionalContext'],
     InstructionsLoaded: [],
     ConfigChange: [],
     DirectoryAdded: [],
     PreModelSwitch: ['permissionDecision', 'permissionDecisionReason'],
     PostModelSwitch: ['additionalContext'],
-    PreToolUse: ['additionalContext', 'permissionDecision', 'permissionDecisionReason', 'updatedInput'],
     PermissionRequest: ['decision'],
     PermissionDenied: ['retry'],
-    PostToolUse: ['additionalContext', 'updatedToolOutput', 'updatedMCPToolOutput'],
+    PostToolUse: ['additionalContext'],
     PostToolUseFailure: ['additionalContext'],
     PostToolBatch: ['additionalContext'],
     MessageDisplay: ['displayContent'],
@@ -41,27 +39,17 @@ const readFields = {
     WorktreeCreate: ['worktreePath'],
     WorktreeRemove: [],
 };
-export function classicHook(name, event, hook, claude, calls, report) {
-    const hookInputOf = async (e) => {
-        if (event !== 'PostToolUse' && event !== 'PostToolUseFailure')
-            return e;
-        const input = e;
-        const cwd = calls.cwdOf(input.tool_use_id) ?? input.cwd;
-        return { ...input, files: await callFiles(name, claude, { tool: input.tool_name, input: inputOf(input.tool_input) }, cwd) };
-    };
-    const resultOf = async (e) => {
-        const answer = await hook((await hookInputOf(e)));
-        if (answer === undefined)
-            return undefined;
-        if (answer.systemMessage !== undefined)
-            claude.ui.log(answer.systemMessage);
-        return classicResult(event, answer);
-    };
+export function classicHook(name, event, hook, report) {
     const routed = async (e, next) => {
-        const ours = await resultOf(e).catch((error) => {
+        const ours = await Promise.resolve()
+            .then(async () => {
+            const answer = await hook(e);
+            return answer === undefined ? undefined : classicResult(event, answer);
+        })
+            .catch((error) => {
             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 { decision: { behavior: 'deny', message: `${name}: the ${event} listener failed: ${messageOf(error)}` } };
+            report({ id: `hook:${event}`, message: `The ${event} listener failed`, error });
             return undefined;
         });
         if (ours === undefined)
@@ -70,57 +58,6 @@ export function classicHook(name, event, hook, claude, calls, report) {
     };
     return routed;
 }
-export function preToolUseHook(name, hook, claude, calls, held) {
-    return async (e, next) => {
-        let ours;
-        try {
-            const answer = await hook(await preToolUseInput(name, e, claude, calls.agentOf));
-            if (answer?.systemMessage !== undefined)
-                claude.ui.log(answer.systemMessage);
-            ours = answer === undefined ? {} : classicResult('PreToolUse', answer);
-        }
-        catch (error) {
-            return { deny: `${name}: the PreToolUse hook failed: ${messageOf(error)}` };
-        }
-        if (typeof ours['deny'] === 'string')
-            return { deny: ours['deny'] };
-        const decided = heldDecisionOf(ours);
-        if (decided !== undefined && held === undefined) {
-            return { deny: `${name}: the PreToolUse hook answered permissionDecision "${decided.decision}", so hooks/register.ts must call registerPermissionCheck(addHook) after registerMod.` };
-        }
-        const updated = ours['updatedInput'];
-        const reserved = Object.fromEntries(Object.entries(e).filter(([key]) => reservedKeys.includes(key)));
-        const earlier = held?.get(e.tool_use_id);
-        if (decided !== undefined)
-            held?.set(e.tool_use_id, earlier !== undefined && strictness.indexOf(earlier.decision) >= strictness.indexOf(decided.decision) ? earlier : decided);
-        let result;
-        try {
-            result = await next(updated === undefined ? e : { ...reserved, ...updated });
-        }
-        finally {
-            if (decided !== undefined)
-                held?.delete(e.tool_use_id);
-        }
-        const context = ours['additionalContext'];
-        if (context === undefined || result.deny !== undefined)
-            return result;
-        return { ...result, context: [...(result.context ?? []), ...context] };
-    };
-}
-export function heldDecisionHook(held) {
-    return async (e, next) => {
-        const below = await next(e);
-        const ours = e.tool_use_id === undefined ? undefined : held.get(e.tool_use_id);
-        return ours === undefined || below.decision === 'deny' ? below : ours;
-    };
-}
-function heldDecisionOf(ours) {
-    if (ours['allow'] !== undefined)
-        return { decision: 'allow' };
-    if (typeof ours['ask'] !== 'string')
-        return undefined;
-    return ours['ask'] === '' ? { decision: 'ask' } : { decision: 'ask', reason: ours['ask'] };
-}
 const frontmatter = /^---\r?\n[\s\S]*?\r?\n---[ \t]*(?:\r?\n|$)/;
 const baseDirectoryLine = /^Base directory for this skill: [^\n]*\n\n/;
 export function userSkillHook(claude) {
@@ -143,23 +80,7 @@ export function userSkillHook(claude) {
         return next(e);
     };
 }
-async function preToolUseInput(name, envelope, claude, agentOf) {
-    const { tool, tool_use_id } = envelope;
-    const [session_id, cwd, { agentId, agentType }] = await Promise.all([claude.session.id(), claude.session.cwd(), agentOf(tool_use_id)]);
-    const tool_input = toolInputOf(envelope);
-    return {
-        session_id,
-        cwd,
-        hook_event_name: 'PreToolUse',
-        tool_name: tool,
-        tool_input,
-        tool_use_id,
-        ...(agentId === undefined ? {} : { agent_id: agentId }),
-        ...(agentType === undefined ? {} : { agent_type: agentType }),
-        files: await callFiles(name, claude, { tool, input: tool_input }, cwd),
-    };
-}
-async function callFiles(name, claude, use, cwd) {
+export async function callFiles(name, claude, use, cwd) {
     try {
         const [home, configRoot] = await Promise.all([claude.env.home(), claude.env.configHome()]);
         if (home === undefined)
@@ -181,42 +102,18 @@ async function callFiles(name, claude, use, cwd) {
 }
 function classicResult(event, answer) {
     const result = {};
-    const unread = (field) => new Error(`it answered ${field}, which ${event} does not read. Remove it from the answer.`);
-    if (event === 'PreToolUse') {
-        if (answer.continue === false || answer.stopReason !== undefined)
-            throw unread('continue or stopReason');
-        if (answer.decision === 'block')
-            result['deny'] = answer.reason ?? '';
-    }
-    else {
-        if (answer.continue === false)
-            result['preventContinuation'] = true;
-        if (answer.stopReason !== undefined)
-            result['stopReason'] = answer.stopReason;
-        if (answer.decision === 'block')
-            result['block'] = answer.reason ?? '';
-    }
+    if (answer.decision === 'block')
+        result['block'] = answer.reason ?? '';
     const specific = answer.hookSpecificOutput ?? {};
-    if (specific.hookEventName !== undefined && specific.hookEventName !== event) {
-        throw new Error(`it answered hookSpecificOutput.hookEventName "${specific.hookEventName}". Set it to "${event}" or leave it out.`);
-    }
     for (const [field, value] of Object.entries(specific)) {
-        if (field === 'hookEventName' || value === undefined || (value === false && flags.includes(field)))
+        if (field === 'hookEventName' || (value === false && flags.includes(field)))
             continue;
         if (!readFields[event].includes(field))
-            throw unread(`hookSpecificOutput.${field}`);
-        if (field === 'additionalContext')
-            result['additionalContext'] = [value];
-        else if (field === 'permissionDecision' && event === 'PreToolUse') {
-            const reason = specific.permissionDecisionReason ?? '';
-            result[value] = value === 'allow' ? true : reason;
-        }
-        else if (field !== 'permissionDecisionReason' || event !== 'PreToolUse')
-            result[field] = value;
+            throw new Error(`it answered ${field}, which ${event} does not read.`);
+        result[field] = field === 'additionalContext' ? [value] : value;
     }
     return result;
 }
-export const strictness = ['allow', 'ask', 'deny'];
 function mergeClassic(below, ours) {
     const merged = { ...below, ...ours };
     const context = [...(below['additionalContext'] ?? []), ...(ours['additionalContext'] ?? [])];

package/runtime/lifecycle.d.ts

@@ -1,5 +1,5 @@
 import type { Args, EventResult, Frozen, PluginOptions } from 'claude-code';
-import { type Mod, type ModDefinition } from '../mod.js';
+import type { Mod, ModDefinition } from '../mod.js';
 import type { Options } from '../options.js';
 import { type Steps } from '../records.js';
 import type { Claude } from './claude.js';
@@ -24,6 +24,7 @@ export type Lifecycle<State extends object> = {
     readonly toasts: readonly ShownToast[];
     start(claude: Claude, read: (claude: Claude) => Promise<Plugin>): Promise<void>;
     route<N extends RoutedEvent>(event: N, e: Frozen<Args<N>>, next: RouterNext<N>): Promise<EventResult<N>>;
+    raise(method: string, payload: Readonly<Record<string, unknown>>): Promise<unknown>;
 };
 export declare function readPlugin(claude: Claude): Promise<Plugin>;
 export declare function createLifecycle<State extends object, Declared extends Options = Options>(definition: ModDefinition<State, string, Declared>, checksPermissions?: () => boolean, options?: PluginOptions, asksPerson?: boolean): Lifecycle<State>;

package/runtime/lifecycle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../src/runtime/lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAc,aAAa,EAAwB,MAAM,aAAa,CAAA;AAE7G,OAAO,EAAkI,KAAK,GAAG,EAAE,KAAK,aAAa,EAAkD,MAAM,WAAW,CAAA;AACxO,OAAO,KAAK,EAAE,OAAO,EAAgB,MAAM,eAAe,CAAA;AAC1D,OAAO,EAA2T,KAAK,KAAK,EAAE,MAAM,eAAe,CAAA;AAGnW,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAOzC,OAAO,EAAsG,KAAK,WAAW,EAAE,MAAM,YAAY,CAAA;AAOjJ,OAAO,EAA6B,KAAK,UAAU,EAAE,MAAM,aAAa,CAAA;AAMxE,OAAO,EAA+B,KAAK,UAAU,EAAgB,MAAM,cAAc,CAAA;AAMzF,MAAM,MAAM,MAAM,GAAG;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;IAC7B,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;IAC9B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CACpC,CAAA;AAED,MAAM,MAAM,KAAK,GAAG,UAAU,GAAG,YAAY,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAA;AAEtG,MAAM,MAAM,SAAS,CAAC,KAAK,SAAS,MAAM,IAAI;IAC5C,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,SAAS,CAAA;IACpC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAA;IACtC,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/E,KAAK,CAAC,CAAC,SAAS,WAAW,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAA;CACzG,CAAA;AAwCD,wBAAsB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAwBhE;AAkCD,wBAAgB,eAAe,CAAC,KAAK,SAAS,MAAM,EAAE,QAAQ,SAAS,OAAO,GAAG,OAAO,EACtF,UAAU,EAAE,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAClD,iBAAiB,GAAE,MAAM,OAAoB,EAC7C,OAAO,GAAE,aAAkB,EAC3B,UAAU,UAAO,GAChB,SAAS,CAAC,KAAK,CAAC,CAkclB"}
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../src/runtime/lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAc,aAAa,EAAwB,MAAM,aAAa,CAAA;AAE7G,OAAO,KAAK,EAA4C,GAAG,EAAE,aAAa,EAAmF,MAAM,WAAW,CAAA;AAC9K,OAAO,KAAK,EAAE,OAAO,EAAgB,MAAM,eAAe,CAAA;AAC1D,OAAO,EAA2T,KAAK,KAAK,EAAE,MAAM,eAAe,CAAA;AAGnW,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAOzC,OAAO,EAA8E,KAAK,WAAW,EAAE,MAAM,YAAY,CAAA;AAOzH,OAAO,EAA6B,KAAK,UAAU,EAAE,MAAM,aAAa,CAAA;AAMxE,OAAO,EAA+B,KAAK,UAAU,EAAgB,MAAM,cAAc,CAAA;AAMzF,MAAM,MAAM,MAAM,GAAG;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;IAC7B,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;IAC9B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CACpC,CAAA;AAED,MAAM,MAAM,KAAK,GAAG,UAAU,GAAG,YAAY,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAA;AAEtG,MAAM,MAAM,SAAS,CAAC,KAAK,SAAS,MAAM,IAAI;IAC5C,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,SAAS,CAAA;IACpC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAA;IACtC,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/E,KAAK,CAAC,CAAC,SAAS,WAAW,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAA;IACxG,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CACpF,CAAA;AAyCD,wBAAsB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAwBhE;AAkCD,wBAAgB,eAAe,CAAC,KAAK,SAAS,MAAM,EAAE,QAAQ,SAAS,OAAO,GAAG,OAAO,EACtF,UAAU,EAAE,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAClD,iBAAiB,GAAE,MAAM,OAAoB,EAC7C,OAAO,GAAE,aAAkB,EAC3B,UAAU,UAAO,GAChB,SAAS,CAAC,KAAK,CAAC,CAyclB"}

package/runtime/lifecycle.js

@@ -1,4 +1,3 @@
-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 { homePrefix, ifMissing, relativePath } from '../utils/paths.js';
 import { firstLine, formatExit, listed, messageOf } from '../utils/text.js';
@@ -6,9 +5,9 @@ import { beforeDeadline } from './deadline.js';
 import { announcedOf, announcementMs, announcementOf } from './announce.js';
 import { bind } from './bound.js';
 import { serveConversations } from './conversations.js';
-import { answerCall, cmodPluginName, dependencyCalls, withBareRefusals } from './dependencies.js';
+import { answerCall, answeringOwnCalls, cmodPluginName, dependencyCalls, withBareRefusals } from './dependencies.js';
 import { keepEngine } from './engine.js';
-import { classicHook, heldDecisionHook, permissionEvents, preToolUseHook, userSkillHook } from './hooks.js';
+import { classicHook, permissionEvents, userSkillHook } from './hooks.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';
@@ -103,6 +102,7 @@ export function createLifecycle(definition, checksPermissions = () => true, opti
     let activation;
     let mod;
     let imports;
+    let raise;
     let failure;
     let pluginOptions = options;
     const installer = createInstaller(definition.name, () => claude());
@@ -261,6 +261,7 @@ export function createLifecycle(definition, checksPermissions = () => true, opti
         const { added } = active;
         mod = active.mod;
         imports = active.imports;
+        raise = active.raise;
         router = activeRouter;
         phase = 'active';
         runtime.claude.ui.invalidate('ui.render');
@@ -502,6 +503,12 @@ export function createLifecycle(definition, checksPermissions = () => true, opti
         get toasts() {
             return runtime?.toaster.shown ?? [];
         },
+        async raise(method, payload) {
+            if (raise === undefined || imports === undefined)
+                throw new Error(`${definition.name} has not started, so ${method} has no listener yet.`);
+            bind(imports);
+            return raise(method, payload);
+        },
         async start(claudeCalls, read) {
             if (runtime !== undefined)
                 return;
@@ -565,9 +572,8 @@ export function createLifecycle(definition, checksPermissions = () => true, opti
 async function createMod(definition, runtime) {
     const { router, toaster } = runtime;
     const report = (failure) => void toaster.fail(failure);
-    const claude = withBareRefusals(checkingKeys(runtime.claude, toaster.toast, runtime.steps.keys ?? {}));
+    const claude = answeringOwnCalls(withBareRefusals(checkingKeys(runtime.claude, toaster.toast, runtime.steps.keys ?? {})), router);
     const added = [];
-    const hooksAdded = [];
     const announce = (feature) => {
         added.push(feature);
     };
@@ -640,17 +646,26 @@ async function createMod(definition, runtime) {
     }));
     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 hookOn = (hook, listener) => router.add(`classic.${hook}`, classicHook(definition.name, hook, listener, report));
     const expand = (path) => (homePrefix.test(path) ? resolvedPath(path, places) : path);
     const settingsFile = (source) => ({
         read: () => checked.settings.read({ source }),
         async update(values) {
-            await checkSettings(grants, source, Object.keys(values));
+            await checkSettings(grants, source, 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 }), isGranted: (permission) => flag(permission) });
+    const client = createSessionsClient({
+        name: definition.name,
+        claude: checked,
+        report: (id, message, error) => report({ id, message, error }),
+        isGranted: (permission) => flag(permission),
+        hookOn: (hook, listener) => hookOn(hook, listener),
+        routeOn: (event, hook) => router.add(event, hook),
+    });
     let followed;
+    let isSetUp = false;
+    const watches = new Set();
     const followFolders = (project, folder) => {
         if (followed === undefined)
             return;
@@ -659,7 +674,16 @@ async function createMod(definition, runtime) {
     };
     const imports = {
         sessions: client.sessions,
-        settings: {
+        commands: {
+            list: async () => (await checked.command.list()).map(({ name, description, source, plugin }) => ({ name, description, source, ...(plugin === undefined ? {} : { plugin }) })),
+            run: async (command, args) => {
+                const { text, context } = await checked.command.run({ command, ...(args === undefined ? {} : { args }) });
+                return { ...(text === undefined ? {} : { text }), ...(context === undefined || context.length === 0 ? {} : { note: context.join('\n') }) };
+            },
+            beforeRun: (...args) => client.listen('beforeRun', args),
+            onRun: (...args) => client.listen('onRun', args),
+        },
+        config: {
             list: async () => (await checked.config.list()).map(({ key, label, description, kind, value, options, provider, isLocked }) => ({
                 key,
                 label,
@@ -670,9 +694,22 @@ async function createMod(definition, runtime) {
                 ...(options === undefined ? {} : { options }),
                 ...(provider.plugin === 'engine' ? {} : { plugin: provider.plugin }),
             })),
+        },
+        settings: {
             user: settingsFile('user'),
             project: settingsFile('project'),
             local: settingsFile('local'),
+            beforeFileChange: (matcherOrListener, maybeListener) => {
+                const listener = (maybeListener ?? matcherOrListener);
+                const matcher = maybeListener === undefined ? undefined : matcherOrListener;
+                return hookOn('ConfigChange', async ({ source, file_path }) => {
+                    const change = { source: source === 'skills' ? 'skills' : source.replace('_settings', ''), ...(file_path === undefined ? {} : { path: file_path }) };
+                    if (matcher !== undefined && !matches(change, matcher))
+                        return undefined;
+                    const answer = await listener(change);
+                    return answer === undefined ? undefined : { decision: 'block', reason: answer.refuse };
+                });
+            },
         },
         model: { complete: (completion, options) => checked.model.complete(completion, options) },
         fs: {
@@ -685,6 +722,22 @@ async function createMod(definition, runtime) {
                 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 }) };
             },
+            onChange({ path }, listener) {
+                if (isSetUp)
+                    throw new Error(`${definition.name}: fs.onChange works only in setup, because Claude Code reads the paths it watches when a session starts.`);
+                const paths = [path].flat().map((each) => resolvedPath(each, places));
+                const watch = { paths, listener };
+                watches.add(watch);
+                if (watches.size === 1) {
+                    hookOn('SessionStart', () => ({ hookSpecificOutput: { watchPaths: [...new Set([...watches].flatMap((each) => each.paths))] } }));
+                    hookOn('FileChanged', ({ file_path, event }) => {
+                        for (const each of watches)
+                            if (each.paths.some((watched) => relativePath(watched, file_path) !== undefined))
+                                void Promise.resolve(each.listener({ path: file_path, type: event })).catch((error) => report({ id: 'fs:onChange', message: 'The fs.onChange listener failed', error }));
+                    });
+                }
+                return { dispose: () => void watches.delete(watch) };
+            },
         },
         metadata: {
             read: (path) => files.read(path),
@@ -748,26 +801,10 @@ async function createMod(definition, runtime) {
             files: allowed('files'),
             config: allowed('config'),
         },
-        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' }),
+        log: (text, options) => claude.ui.log(`${definition.name}: ${text}`, { to: options?.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)),
@@ -858,9 +895,9 @@ async function createMod(definition, runtime) {
             return next(e);
         const call = e;
         if (e.method === conversationMethods.changed && call.caller === cmodPluginName) {
-            if (!flag('conversation'))
-                return { value: null };
             const { session: changedSession, change, isInProject } = e.input;
+            if (changedSession !== client.sessions.current.id && !flag('conversation'))
+                return { value: null };
             client.changed(changedSession, change, isInProject !== false);
             return { value: null };
         }
@@ -894,16 +931,13 @@ async function createMod(definition, runtime) {
         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));
+    isSetUp = true;
     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 && hooksAdded.includes(PreToolUse))
-        router.add('tool.check', heldDecisionHook(held));
     await failsAs('its open panes did not load', () => area.restorePanes());
-    if (hooksAdded.length > 0)
-        added.push(`${hooksAdded.length === 1 ? 'a hook' : 'hooks'} on ${listed(hooksAdded)}`);
-    return { mod, added, imports };
+    return { mod, added, imports, raise: client.raise };
 }
 function checkingKeys(claude, toast, keys) {
     const bound = Object.entries(keys);
@@ -925,23 +959,6 @@ 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(event, hook, ms, claude, toast) {
-    return (input) => new Promise((resolve, reject) => {
-        const timer = claude.clock.after(ms, () => {
-            toast.warning(`The ${event} hook passed its ${ms / 1000} s timeout`, { id: `timeout:${event}` });
-            resolve(undefined);
-        });
-        Promise.resolve()
-            .then(() => hook(input))
-            .then((answer) => {
-            timer.cancel();
-            resolve(answer);
-        }, (error) => {
-            timer.cancel();
-            reject(error);
-        });
-    });
-}
 async function failsAs(subject, step) {
     try {
         await step();