@cmodjs/core 0.1.10 → 0.1.12

package/runtime/lifecycle.js

@@ -30,12 +30,12 @@ export async function readPlugin(claude) {
     const manifest = (await readJson(read, `${root}/.claude-plugin/plugin.json`));
     const version = typeof manifest?.version === 'string' ? manifest.version : undefined;
     const store = storeFolder({ HOME: await claude.env.home(), XDG_DATA_HOME: await claude.env.dataHome() });
-    const plugin = { name, root, version, store };
     if (name === cmodPluginName) {
         const installed = await cmodVersion(claude);
-        return { ...plugin, isInstalled: version !== undefined && installed !== undefined && isAtLeast(installed, version), shouldRecord: false };
+        return { name, root, version, store, keys: {}, isInstalled: version !== undefined && installed !== undefined && isAtLeast(installed, version), shouldRecord: false };
     }
     const steps = readSteps(await readJson(read, `${root}/package.json`)) ?? {};
+    const plugin = { name, root, version, store, keys: steps.keys ?? {} };
     const record = await readRecord(read, store, name);
     if (Object.keys(steps).length === 0)
         return { ...plugin, isInstalled: true, shouldRecord: record?.version !== version };
@@ -136,7 +136,7 @@ export function createLifecycle(definition, checksPermissions = () => true) {
         if (runtime === undefined || plugin === undefined)
             return;
         const activeRouter = createRouter();
-        const active = await createMod(definition, { ...runtime, router: activeRouter, dataFolder: dataFolder(plugin.store, plugin.name), checksPermissions }).catch((error) => {
+        const active = await createMod(definition, { ...runtime, router: activeRouter, dataFolder: dataFolder(plugin.store, plugin.name), keys: plugin.keys, checksPermissions }).catch((error) => {
             fail(messageOf(error), 'Fix it, then run /reload-plugins.');
             throw error;
         });
@@ -171,8 +171,12 @@ export function createLifecycle(definition, checksPermissions = () => true) {
             return;
         }
         showLine().wait('Waiting for your answer');
-        const removal = event.uninstall === '' ? '' : `, and ${event.uninstall} when you remove it`;
-        const answer = await claude().ui.ask(`${name} runs ${event.install} to install${removal}. Run it now?`, { options: ['Install', 'Not now'], header: 'Install' });
+        const actions = [
+            ...(event.install === '' ? [] : [`runs ${event.install} to install`]),
+            ...(event.uninstall === '' ? [] : [`runs ${event.uninstall} when you remove it`]),
+            ...(event.keys === '' ? [] : [`binds ${event.keys}`]),
+        ];
+        const answer = await claude().ui.ask(`${name} ${listed(actions)}. Install it now?`, { options: ['Install', 'Not now'], header: 'Install' });
         if (answer === 'Install')
             return install(event.sha256);
         phase = 'declined';
@@ -320,7 +324,8 @@ export function createLifecycle(definition, checksPermissions = () => true) {
     };
 }
 async function createMod(definition, runtime) {
-    const { claude, router, progress } = runtime;
+    const { router, progress } = runtime;
+    const claude = checkingKeys(runtime.claude, definition.name, runtime.keys);
     const added = [];
     const hookEvents = [];
     const announce = (feature) => {
@@ -337,15 +342,30 @@ async function createMod(definition, runtime) {
         name: definition.name,
         state: modState.state,
         dataFolder: runtime.dataFolder,
-        on(event, hook) {
+        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, hook, claude, agents, held));
+                router.add('tool.call', preToolUseHook(definition.name, bounded, claude, agents, held));
             else
-                router.add(`classic.${event}`, classicHook(definition.name, event, hook, claude, agents));
+                router.add(`classic.${event}`, classicHook(definition.name, event, bounded, claude, agents));
         },
         use: (job) => job({ mod, claude, on: (event, hook) => router.add(event, hook), 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) => claude.process.run(argv, init),
@@ -360,8 +380,21 @@ async function createMod(definition, runtime) {
         },
         http: { fetch: (url, init) => claude.http.fetch(url, init) },
         settings: { read: (args) => claude.settings.read(args) },
-        session: { messages: claude.session.messages },
+        session: {
+            messages: claude.session.messages,
+            async append(text) {
+                const added = await claude.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 claude.prompt.submit({ text });
+                if ('drop' in submitted && typeof submitted.drop === 'string')
+                    throw new Error(`${definition.name}: Claude Code dropped the prompt: ${submitted.drop}`);
+            },
+        },
         agent: { spawn: (args) => claude.agent.spawn(args) },
+        model: { complete: (request, options) => claude.model.complete(request, options) },
         get projectRoot() {
             return modState.root;
         },
@@ -448,6 +481,43 @@ async function createMod(definition, runtime) {
         added.push(`${hookEvents.length === 1 ? 'a hook' : 'hooks'} on ${listed(hookEvents)}`);
     return { mod, added };
 }
+function checkingKeys(claude, name, 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.`);
+            }
+        }
+        return claude.command.register(command);
+    };
+    return { ...claude, command: { ...claude.command, register } };
+}
+const longestTimerMs = 2_147_483_647;
+function checkedMs(name, subject, ms) {
+    if (!Number.isInteger(ms) || ms <= 0 || ms > longestTimerMs)
+        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) {
+    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`);
+            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();

package/runtime/state.d.ts

@@ -15,5 +15,6 @@ export type ModState<State extends object> = {
     moveTo(root: string): Promise<void>;
     switchSession(session: string, source: ClassicHookInputs['SessionStart']['source']): Promise<void>;
 };
-export declare function createState<State extends object>({ name, initial, session, root, claude, changed }: StateOptions): ModState<State>;
+export declare function onStateChange(state: object, listener: () => void): void;
+export declare function createState<State extends object>({ name, initial, session, root, claude, changed: redraw }: StateOptions): ModState<State>;
 //# sourceMappingURL=state.d.ts.map

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;AAQD,wBAAgB,WAAW,CAAC,KAAK,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,YAAY,GAAG,QAAQ,CAAC,KAAK,CAAC,CAqIlI"}
+{"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"}

package/runtime/state.js

@@ -3,7 +3,18 @@ import { messageOf } from '../utils/text.js';
 const lifetimes = ['memory', 'session', 'project', 'global'];
 const savedLifetimes = ['session', 'project', 'global'];
 const keptPerValue = 20;
-export function createState({ name, initial, session, root, claude, changed }) {
+const listeners = new WeakMap();
+export function onStateChange(state, listener) {
+    const own = listeners.get(state) ?? new Set();
+    own.add(listener);
+    listeners.set(state, own);
+}
+export function createState({ name, initial, session, root, claude, changed: redraw }) {
+    const changed = () => {
+        redraw();
+        for (const listener of listeners.get(state) ?? [])
+            listener();
+    };
     const declared = declaredGroups(name, initial);
     const current = copied(declared);
     let defaults = declared;

package/src/jobs/check.ts

@@ -1,6 +1,6 @@
 import type { Job } from '../mod.js'
 import { longestMs, type Deadline } from '../runtime/deadline.js'
-import { callEffects, type ToolUse } from '../utils/call-effects.js'
+import { callEffects, type ToolCall } from '../utils/call-effects.js'
 import { dirname } from '../vendor.js'
 import { listed, messageOf } from '../utils/text.js'
 import { afterCall, modOf, targetWords } from './context.js'
@@ -39,7 +39,7 @@ export function check<State extends object = Record<never, never>>(options: { re
   }
 }
 
-async function triggeredRun(after: readonly Target[], run: readonly string[], use: ToolUse, workspace: Workspace): Promise<{ command: string[]; folder: string } | undefined> {
+async function triggeredRun(after: readonly Target[], run: readonly string[], use: ToolCall, workspace: Workspace): Promise<{ command: string[]; folder: string } | undefined> {
   const effects = callEffects(use, workspace)
   const paths = new Set<string>()
   let commandFolder: string | undefined

package/src/jobs/context.ts

@@ -5,7 +5,7 @@ import { beforeDeadline, type Deadline } from '../runtime/deadline.js'
 import { dependencyCalls } from '../runtime/dependencies.js'
 import { toolInputOf } from '../runtime/tool-calls.js'
 import { listed } from '../utils/text.js'
-import type { ToolCall, ToolUse } from '../utils/call-effects.js'
+import type { ToolCall } from '../utils/call-effects.js'
 import { findProjectScope, type Workspace } from './permissions/find-project-scope.js'
 import { targetOf, type Target } from './permissions/match-target.js'
 import type { FileSystem } from '../utils/paths.js'
@@ -36,7 +36,7 @@ async function readSession(claude: Claude): Promise<Session> {
 
 export function afterCall<State extends object>(
   job: JobContext<State>,
-  contextAfter: (use: ToolUse, workspace: Workspace) => Promise<readonly string[]>,
+  contextAfter: (call: ToolCall, workspace: Workspace) => Promise<readonly string[]>,
   failed: (error: unknown) => readonly string[],
 ): void {
   const readWorkspace = workspaceReader(job)
@@ -50,7 +50,7 @@ export function afterCall<State extends object>(
   })
 }
 
-async function useOf({ toolCalls }: JobContext, e: Frozen<Args<'tool.call'>>): Promise<ToolUse> {
+async function useOf({ toolCalls }: JobContext, e: Frozen<Args<'tool.call'>>): Promise<ToolCall> {
   return { tool: e.tool, input: toolInputOf(e), ...(await toolCalls.agentOf(e.tool_use_id)) }
 }
 
@@ -109,8 +109,8 @@ function spawnWithin(claude: Claude, deadline: Deadline, started: Promise<Stream
 }
 
 export function targetWords(target: Target): string {
-  const { key, patterns } = targetOf(target)
-  const named = listed(patterns)
+  const { key, patterns, exclusions } = targetOf(target)
+  const named = exclusions.length === 0 ? listed(patterns) : `${listed(patterns)} except ${listed(exclusions)}`
   if (key === 'command') return patterns.includes('*') ? 'every shell command' : named
   if (key === 'write') return `edits to ${named}`
   if (key === 'read') return `reads of ${named}`

package/src/jobs/permissions/decide-permission.ts

@@ -1,6 +1,6 @@
 import { strictness } from '../../runtime/hooks.js'
 import { messageOf } from '../../utils/text.js'
-import { callBaseOf, callEffects, type CallEffects, type ToolCall, type ToolUse } from '../../utils/call-effects.js'
+import { callBaseOf, callEffects, type CallEffects, type ToolCall } from '../../utils/call-effects.js'
 import type { Workspace } from './find-project-scope.js'
 import { folderInScope, matchTarget, targetOf, type MatchedCall, type Target, type TargetCalls, type TargetKey, type TargetOf } from './match-target.js'
 import { resolve } from '../../vendor.js'
@@ -22,7 +22,7 @@ export function stricterVerdict<Result extends Verdict>(first: Result, second: R
   return strictness.indexOf(second.decision) > strictness.indexOf(first.decision) ? second : first
 }
 
-export async function decidePermission<Mod>(rules: PermissionRules<Mod>, use: ToolUse, workspace: Workspace, modOf: (call: ToolCall, folder: string) => Mod): Promise<Verdict | undefined> {
+export async function decidePermission<Mod>(rules: PermissionRules<Mod>, use: ToolCall, workspace: Workspace, modOf: (call: ToolCall, folder: string) => Mod): Promise<Verdict | undefined> {
   try {
     const effects = callEffects(use, workspace)
     for (const decision of ['deny', 'ask'] as const) {
@@ -39,7 +39,7 @@ export async function decidePermission<Mod>(rules: PermissionRules<Mod>, use: To
   }
 }
 
-async function ruleOutcome<Mod>(rule: Rule<Mod>, use: ToolUse, effects: CallEffects, workspace: Workspace, modOf: (call: ToolCall, folder: string) => Mod): Promise<{ failure: string | undefined } | undefined> {
+async function ruleOutcome<Mod>(rule: Rule<Mod>, use: ToolCall, effects: CallEffects, workspace: Workspace, modOf: (call: ToolCall, folder: string) => Mod): Promise<{ failure: string | undefined } | undefined> {
   const matched = await matchTarget(rule, use, effects, workspace)
   const calls = matched.length > 0 ? matched : await unparsedMatches(rule, use, effects, workspace)
   if (calls.length === 0) return undefined
@@ -56,7 +56,7 @@ async function ruleOutcome<Mod>(rule: Rule<Mod>, use: ToolUse, effects: CallEffe
   return undefined
 }
 
-async function unparsedMatches(target: Target, use: ToolUse, effects: CallEffects, workspace: Workspace): Promise<MatchedCall[]> {
+async function unparsedMatches(target: Target, use: ToolCall, effects: CallEffects, workspace: Workspace): Promise<MatchedCall[]> {
   const shell = effects.shell
   if (shell === undefined || shell.isFullyParsed) return []
   const { key, patterns } = targetOf(target)

package/src/jobs/permissions/match-target.ts

@@ -1,6 +1,6 @@
 import { matchesGlob } from '../../utils/matches-glob.js'
 import { parseShell } from '../../utils/parse-shell.js'
-import { callBaseOf, type CallBase, type CallEffects, type CommandCall, type FetchCall, type FileAccess, type FileCall, type ToolCall, type ToolUse } from '../../utils/call-effects.js'
+import { callBaseOf, type CallBase, type CallEffects, type CommandCall, type FetchCall, type FileAccess, type FileCall, type ToolCall } from '../../utils/call-effects.js'
 import type { Workspace } from './find-project-scope.js'
 import { realPathOf, relativePath } from '../../utils/paths.js'
 import { basename } from '../../vendor.js'
@@ -13,45 +13,53 @@ export type MatchedCall = { call: ToolCall; access: FileAccess | undefined; fold
 
 const targetKeys: readonly TargetKey[] = ['command', 'read', 'write', 'fetch', 'subagent', 'tool']
 
-export function targetOf(target: Target): { key: TargetKey; patterns: string[] } {
+export function targetOf(target: Target): { key: TargetKey; patterns: string[]; exclusions: string[] } {
   const keys = targetKeys.filter((key) => key in target)
   const key = keys[0]
   const value: unknown = key === undefined ? undefined : (target as Partial<Record<TargetKey, unknown>>)[key]
   if (key === undefined || keys.length > 1 || !(typeof value === 'string' || (Array.isArray(value) && value.every((pattern) => typeof pattern === 'string')))) {
     throw new Error(`A rule names exactly one of ${targetKeys.join(', ')} with a pattern or a list of patterns; this one names ${keys.join(' and ') || 'none'}.`)
   }
-  return { key, patterns: typeof value === 'string' ? [value] : value }
+  const all = typeof value === 'string' ? [value] : value
+  const patterns = all.filter((pattern) => !pattern.startsWith('!'))
+  if (patterns.length === 0) throw new Error(`A ${key} target needs a pattern without "!" for its "!" patterns to leave calls out of, such as ['**', ${all.map((pattern) => `'${pattern}'`).join(', ')}].`)
+  return { key, patterns, exclusions: all.filter((pattern) => pattern.startsWith('!')).map((pattern) => pattern.slice(1)) }
 }
 
-export async function matchTarget(target: Target, use: ToolUse, effects: CallEffects, workspace: Workspace): Promise<MatchedCall[]> {
-  const { key, patterns } = targetOf(target)
-  const base = callBaseOf(use)
-  const only = (call: ToolCall, folder = workspace.cwd): MatchedCall[] => [{ call, access: undefined, folder }]
+export async function matchTarget(target: Target, call: CallBase, effects: CallEffects, workspace: Workspace): Promise<MatchedCall[]> {
+  const { key, patterns, exclusions } = targetOf(target)
+  const base = callBaseOf(call)
+  const only = (matched: ToolCall, folder = workspace.cwd): MatchedCall[] => [{ call: matched, access: undefined, folder }]
+  const isNamed = (value: string) => matchesAny(value, patterns) && !matchesAny(value, exclusions)
   if (key === 'read' || key === 'write') {
     const matched: MatchedCall[] = []
     for (const access of key === 'read' ? effects.reads : effects.writes) {
       const path = await matchedPath(patterns, access.path, workspace)
-      if (path !== undefined) matched.push({ call: { ...base, path }, access, folder: workspace.cwd })
+      const isExcluded = path !== undefined && exclusions.length > 0 && (await matchedPath(exclusions, access.path, workspace)) !== undefined
+      if (path !== undefined && !isExcluded) matched.push({ call: { ...base, path }, access, folder: workspace.cwd })
     }
     return matched
   }
   if (key === 'command') {
     const shell = effects.shell
     if (shell === undefined) return []
-    const call = { ...base, commands: shell.commands.map((command) => command.argv), isFullyParsed: shell.isFullyParsed }
-    if (patterns.includes('*')) {
+    const commandCall = { ...base, commands: shell.commands.map((command) => command.argv), isFullyParsed: shell.isFullyParsed }
+    const isEvery = patterns.includes('*')
+    if (isEvery && exclusions.length === 0) {
       const folder = await folderInScope(shell, workspace)
-      return folder === undefined ? [] : only(call, folder)
+      return folder === undefined ? [] : only(commandCall, folder)
     }
-    const wanted = patterns.map(commandPattern)
+    const wanted = patterns.filter((pattern) => pattern !== '*').map(commandPattern)
+    const unwanted = exclusions.map(commandPattern)
     for (const command of shell.commands) {
-      if (wanted.some((pattern) => commandMatches(pattern, command.argv)) && (await isInScope(command.folder, workspace))) return only(call, command.folder)
+      const isWanted = isEvery || wanted.some((pattern) => commandMatches(pattern, command.argv))
+      if (isWanted && !unwanted.some((pattern) => commandMatches(pattern, command.argv)) && (await isInScope(command.folder, workspace))) return only(commandCall, command.folder)
     }
     return []
   }
-  if (key === 'fetch') return effects.urls.filter((url) => matchesAny(url, patterns)).map((url) => ({ call: { ...base, url }, access: undefined, folder: workspace.cwd }))
-  if (key === 'subagent') return effects.subagent !== undefined && matchesAny(effects.subagent, patterns) ? only(base) : []
-  return matchesAny(use.tool, patterns) ? only(base) : []
+  if (key === 'fetch') return effects.urls.filter(isNamed).map((url) => ({ call: { ...base, url }, access: undefined, folder: workspace.cwd }))
+  if (key === 'subagent') return effects.subagent !== undefined && isNamed(effects.subagent) ? only(base) : []
+  return isNamed(call.tool) ? only(base) : []
 }
 
 function commandPattern(pattern: string): [string, ...string[]] {

package/src/jobs/permissions.ts

@@ -1,7 +1,7 @@
 import type { Args, Frozen } from 'claude-code'
 import type { Job, Mod } from '../mod.js'
 import type { Deadline } from '../runtime/deadline.js'
-import type { ToolUse } from '../utils/call-effects.js'
+import { inputOf } from '../utils/call-effects.js'
 import { decidePermission, stricterVerdict, type PermissionRules as RulesFor, type Rule as RuleFor, type Verdict } from './permissions/decide-permission.js'
 import { targetOf } from './permissions/match-target.js'
 import { messageOf } from '../utils/text.js'
@@ -14,19 +14,24 @@ export type PermissionRules<State extends object = Record<never, never>> = Rules
 
 const deadline: Deadline = { ms: 2000, job: 'permissions' }
 
-export function permissions<State extends object = Record<never, never>>(rules: PermissionRules<State>): Job<void, State> {
-  const count = (rules.deny?.length ?? 0) + (rules.ask?.length ?? 0)
+export function permissions<State extends object = Record<never, never>>(rules: PermissionRules<State> | ((state: State) => PermissionRules<State>)): Job<void, State> {
+  const count = typeof rules === 'function' ? undefined : checkedCount(rules)
   if (count === 0) throw new Error('permissions: give it a deny or an ask rule, or remove it from setup.')
-  for (const rule of [...(rules.deny ?? []), ...(rules.ask ?? [])]) targetOf(rule)
 
   return (job) => {
     const readWorkspace = workspaceReader(job)
 
     const verdictOf = async (e: Frozen<Args<'tool.check'>>): Promise<Verdict | undefined> => {
+      let current: PermissionRules<State>
+      try {
+        current = typeof rules === 'function' ? rules(job.mod.state as State) : rules
+        checkedCount(current)
+      } catch (error) {
+        return { decision: 'deny', reason: `The permission rules of ${job.mod.name} failed, so it denies the call: ${messageOf(error)}` }
+      }
       try {
         const [agent, workspace] = await Promise.all([job.toolCalls.agentOf(e.tool_use_id), readWorkspace()])
-        const use: ToolUse = { tool: e.tool, input: e.input, ...agent }
-        return await decidePermission(rules, use, workspace, (call, folder) => modOf(job, { call, folder }, workspace, deadline))
+        return await decidePermission(current, { tool: e.tool, input: inputOf(e.input), ...agent }, workspace, (call, folder) => modOf(job, { call, folder }, workspace, deadline))
       } catch (error) {
         return { decision: 'deny', reason: `The permissions job could not read the session, so it denies the call: ${messageOf(error)}` }
       }
@@ -36,6 +41,12 @@ export function permissions<State extends object = Record<never, never>>(rules:
       const [below, ours] = await Promise.all([next(e), verdictOf(e)])
       return ours === undefined ? below : stricterVerdict<Verdict>(below, ours)
     })
-    job.announce(`${count} permission rule${count === 1 ? '' : 's'}`)
+    job.announce(count === undefined ? 'permission rules from its state' : `${count} permission rule${count === 1 ? '' : 's'}`)
   }
 }
+
+function checkedCount<Mod>(rules: RulesFor<Mod>): number {
+  const all = [...(rules.deny ?? []), ...(rules.ask ?? [])]
+  for (const rule of all) targetOf(rule)
+  return all.length
+}

package/src/jobs/prompt.ts

@@ -1,5 +1,6 @@
 import type { Job, JobContext, Mod } from '../mod.js'
 import { longestMs, type Deadline } from '../runtime/deadline.js'
+import { onStateChange } from '../runtime/state.js'
 import { listed, messageOf } from '../utils/text.js'
 import { callEffects, type ToolCall } from '../utils/call-effects.js'
 import { matchTarget, targetOf, type Target } from './permissions/match-target.js'
@@ -48,21 +49,48 @@ export function prompt<State extends object = Record<never, never>>({ name, prom
       addAfterCalls(job, targets, headedText, log)
       job.announce(`the ${name} prompt after ${listed(targets.map(targetWords))}`)
     } else {
-      addOncePerConversation(job, name, () => textFor({}, modWithin(job, deadline)), log)
+      addKeptCurrent(job, name, () => textFor({}, modWithin(job, deadline)), log)
       job.announce(`the ${name} prompt`)
     }
   }
 }
 
-function addOncePerConversation(job: JobContext, name: string, textFor: () => Promise<string | undefined>, log: (reason: string) => void): void {
+function addKeptCurrent<State extends object>(job: JobContext<State>, name: string, textFor: () => Promise<string | undefined>, log: (reason: string) => void): void {
+  let given: string | undefined
+  let hasStarted = false
+  let isQueued = false
+  let updates = Promise.resolve()
+
+  job.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) => {
     const below = await next(e)
+    hasStarted = true
     if (below.blocks.some((block) => block.name === name)) {
       log(`a block named "${name}" is already in the context`)
       return below
     }
+    given = await textFor()
+    return given === undefined ? below : { ...below, blocks: [...below.blocks, { name, text: given }] }
+  })
+
+  const update = async () => {
+    isQueued = false
+    if (!hasStarted) return
     const value = await textFor()
-    return value === undefined ? below : { ...below, blocks: [...below.blocks, { name, text: value }] }
+    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) => {
+      if (added.deny !== undefined) log(`Claude Code refused the new text: ${added.deny}`)
+    })
+  }
+  onStateChange(job.mod.state, () => {
+    if (isQueued) return
+    isQueued = true
+    updates = updates.then(update).catch((error: unknown) => log(messageOf(error)))
   })
 }
 

package/src/mod.ts

@@ -10,6 +10,9 @@ import type {
   HookStream,
   HttpInit,
   HttpResponse,
+  ModelCompleteOptions,
+  ModelCompleteRequest,
+  ModelCompleteResult,
   PaneOpenArgs,
   PermissionRequestDecision,
   ProcessRunInit,
@@ -20,6 +23,7 @@ import type {
   RenderElement,
   Settings,
   SettingsReadArgs,
+  Timer,
   ToastOptions,
   UiScrollArgs,
   UiScrollResult,
@@ -117,12 +121,17 @@ export type HookInput<E extends ModEvent> = HookInputs[E]
 
 export type ModHook<E extends ModEvent> = (input: HookInput<E>) => HookAnswer | void | Promise<HookAnswer | void>
 
+export type HookOptions = {
+  readonly timeoutMs?: number
+}
+
 export type Mod<State extends object = Record<never, never>> = {
   readonly name: string
   readonly state: Readonly<State>
   readonly dataFolder: string
-  on<E extends ModEvent>(event: E, hook: ModHook<E>): void
+  on<E extends ModEvent>(event: E, hook: ModHook<E>, options?: HookOptions): void
   use<Handle>(job: Job<Handle, State>): Handle
+  every(ms: number, hook: () => unknown): Timer
   readonly ui: {
     pane(pane: Pane<State>): PaneHandle
     render<S extends Slot>(slot: S, Component: (props: SlotProps<S>) => RenderElement): void
@@ -150,10 +159,15 @@ export type Mod<State extends object = Record<never, never>> = {
   }
   readonly session: {
     messages: Claude['session']['messages']
+    append(text: string): Promise<void>
+    submit(text: string): Promise<void>
   }
   readonly agent: {
     spawn(args: AgentSpawnArgs): Promise<AgentSpawnResult>
   }
+  readonly model: {
+    complete(request: ModelCompleteRequest, options?: ModelCompleteOptions): Promise<ModelCompleteResult>
+  }
   readonly projectRoot: string
   readonly cwd: string
   readonly dependencies: CmodDependencies

package/src/records.ts

@@ -1,4 +1,4 @@
-import { messageOf } from './utils/text.js'
+import { listed, messageOf } from './utils/text.js'
 
 export type InstallRecord = {
   name: string
@@ -8,16 +8,17 @@ export type InstallRecord = {
   scriptsSha256: string
   uninstall: string | null
   program: string | null
+  keys: Readonly<Record<string, string>>
 }
 
-export type Steps = { install?: string; uninstall?: string; program?: string }
+export type Steps = { install?: string; uninstall?: string; program?: string; keys?: Readonly<Record<string, string>> }
 
 export type ReadFile = (path: string) => Promise<string | undefined>
 
 export type RunnerEvent =
   | { kind: 'progress'; done: number; total: number; label: string }
   | { kind: 'log'; text: string }
-  | { kind: 'needs-consent'; sha256: string; install: string; uninstall: string }
+  | { kind: 'needs-consent'; sha256: string; install: string; uninstall: string; keys: string }
   | { kind: 'done'; name: string; version?: string }
   | { kind: 'missing'; name: string }
   | { kind: 'failed'; code: number; message: string }
@@ -89,6 +90,8 @@ function parseRecord(text: string, path: string): InstallRecord {
   if (uninstall !== null && typeof uninstall !== 'string') throw new Error(`${path} has an "uninstall" that is neither a path nor null. ${fix}`)
   const program = value['program']
   if (program !== null && typeof program !== 'string') throw new Error(`${path} has a "program" that is neither a command name nor null. ${fix}`)
+  const keys = value['keys'] ?? {}
+  if (!isObject(keys) || Object.values(keys).some((command) => typeof command !== 'string')) throw new Error(`${path} has "keys" that are not key bindings. ${fix}`)
   return {
     name: value['name'] as string,
     version: value['version'] as string,
@@ -97,6 +100,7 @@ function parseRecord(text: string, path: string): InstallRecord {
     scriptsSha256: value['scriptsSha256'] as string,
     uninstall,
     program,
+    keys: keys as Record<string, string>,
   }
 }
 
@@ -108,7 +112,23 @@ export function readSteps(pkg: unknown): Steps | undefined {
   if (!isObject(steps)) throw new Error('package.json has a "cmod" key that is not an object. Write "cmod": { "install": "./setup/install.sh", "uninstall": "./setup/uninstall.sh" }.')
   const program = steps['program']
   if (program !== undefined && (typeof program !== 'string' || !pluginName.test(program))) throw new Error('package.json "cmod.program" must be the program\'s command, such as "hello".')
-  return { ...readCommand(steps, 'install'), ...readCommand(steps, 'uninstall'), ...(program === undefined ? {} : { program }) }
+  return { ...readCommand(steps, 'install'), ...readCommand(steps, 'uninstall'), ...(program === undefined ? {} : { program }), ...readKeys(steps['keys']) }
+}
+
+function readKeys(keys: unknown): Steps {
+  if (keys === undefined) return {}
+  if (!isObject(keys) || Object.keys(keys).length === 0) throw new Error('package.json "cmod.keys" must bind each key to a command, such as "keys": { "shift+tab": "/mode" }.')
+  const commands: Record<string, string> = {}
+  for (const [key, value] of Object.entries(keys)) {
+    const command = typeof value === 'string' ? /^\/([A-Za-z0-9][A-Za-z0-9._:-]*)$/.exec(value)?.[1] : undefined
+    if (key.trim() === '' || command === undefined) throw new Error(`package.json "cmod.keys" binds "${key}" to ${JSON.stringify(value)}. Bind each key to one of the mod's commands, such as "shift+tab": "/mode".`)
+    commands[key] = command
+  }
+  return { keys: commands }
+}
+
+export function keyWords(keys: Readonly<Record<string, string>> | undefined): string {
+  return listed(Object.entries(keys ?? {}).map(([key, command]) => `${key} to /${command}`))
 }
 
 function readCommand(steps: Record<string, unknown>, key: 'install' | 'uninstall'): Steps {
@@ -145,7 +165,7 @@ export async function scriptsSha256(steps: Steps, files: { read: ReadFile; list:
     if (scriptFolders.length === 0) throw new Error(`package.json "cmod.${key}" runs "${command}", which names no script file in the mod, so consent cannot cover what it runs. Put the commands in a script, such as ./setup/${key}.sh.`)
     for (const folder of scriptFolders) folders.add(folder)
   }
-  let text = [steps.install ?? '', steps.uninstall ?? '', steps.program ?? ''].join('\0')
+  let text = [steps.install ?? '', steps.uninstall ?? '', steps.program ?? '', ...(steps.keys === undefined ? [] : [JSON.stringify(Object.entries(steps.keys).sort())])].join('\0')
   for (const folder of [...folders].sort()) {
     for (const name of (await files.list(folder)).sort()) {
       const path = `${folder}/${name}`
@@ -165,7 +185,7 @@ export function formatEvent(event: RunnerEvent): string {
     case 'log':
       return `log ${event.text}`
     case 'needs-consent':
-      return `needs-consent ${event.sha256}\t${event.install}\t${event.uninstall}`
+      return `needs-consent ${event.sha256}\t${event.install}\t${event.uninstall}\t${event.keys}`
     case 'done':
       return event.version === undefined ? `done ${event.name}` : `done ${event.name} ${event.version}`
     case 'missing':
@@ -178,8 +198,8 @@ export function formatEvent(event: RunnerEvent): string {
 export function parseEvent(line: string): RunnerEvent {
   const progress = /^progress (\d+) (\d+)(?: (.*))?$/.exec(line)
   if (progress !== null) return { kind: 'progress', done: Number(progress[1]), total: Number(progress[2]), label: progress[3] ?? '' }
-  const consent = /^needs-consent (\S+)\t([^\t]*)\t(.*)$/.exec(line)
-  if (consent !== null) return { kind: 'needs-consent', sha256: consent[1] as string, install: consent[2] as string, uninstall: consent[3] as string }
+  const consent = /^needs-consent (\S+)\t([^\t]*)\t([^\t]*)(?:\t(.*))?$/.exec(line)
+  if (consent !== null) return { kind: 'needs-consent', sha256: consent[1] as string, install: consent[2] as string, uninstall: consent[3] as string, keys: consent[4] ?? '' }
   const done = /^done (\S+)(?: (\S+))?$/.exec(line)
   if (done !== null) return { kind: 'done', name: done[1] as string, ...(done[2] === undefined ? {} : { version: done[2] }) }
   const missing = /^missing (\S+)$/.exec(line)

package/src/register.ts

@@ -56,7 +56,10 @@ async function startMod($: EngineInterface, eventInput: Frozen<Args<'session.sta
       usage: () => $.session.usage(),
       surfaces: () => $.session.surfaces(),
       messages: ((args?: Parameters<Claude['session']['messages']>[0]) => (args === undefined ? $.session.messages() : $.session.messages(args))) as Claude['session']['messages'],
+      append: (args) => $.session.append(args),
     },
+    prompt: { submit: (args) => $.prompt.submit(args) },
+    model: { complete: (request, options) => $.model.complete(request, options) },
     command: { register: (command) => $.command.register(command) },
     tool: { register: (tool) => $.tool.register(tool) },
     agent: {

package/src/runtime/claude.ts

@@ -83,7 +83,10 @@ export type Claude = {
     usage(): Promise<SessionUsage>
     surfaces(): Promise<readonly RenderSurface[]>
     messages: EngineInterface['session']['messages']
+    append: EngineInterface['session']['append']
   }
+  readonly prompt: { submit: EngineInterface['prompt']['submit'] }
+  readonly model: { complete: EngineInterface['model']['complete'] }
   readonly command: { register(command: CommandSpec): Promise<{ command: string }> }
   readonly tool: { register(tool: ToolSpec): Promise<{ tool: string }> }
   readonly agent: {