@cmodjs/core 1.6.0 → 2.0.0

package/runtime/sessions.js

@@ -1,15 +1,20 @@
 import { ContextEnd, ContextStart } from '../session/context/context.js';
-import { Message } from '../session/context/turn/message/message.js';
+import { Message, noFiles } from '../session/context/turn/message/message.js';
 import { Note } from '../session/context/turn/message/note.js';
-import { Person } from '../session/context/turn/message/sender.js';
+import { Person, senderOf } from '../session/context/turn/message/sender.js';
+import { ToolCall } from '../session/context/turn/message/tool-call.js';
 import { ToolResult } from '../session/context/turn/message/tool-result.js';
 import { TurnEnd, TurnStart } from '../session/context/turn/turn.js';
+import { searchLimit } from '../session/conversation.js';
 import { GoalChange } from '../session/goal/goal.js';
 import { TaskEnd, TaskStart } from '../session/goal/task.js';
-import { Session } from '../session/session.js';
+import { beforeEvents, processEvents, Session, sessionEvents } from '../session/session.js';
 import { matches, sentMatcher } from '../utils/matcher.js';
 import { foldAnswers } from './before.js';
 import { cmodPluginName } from './dependencies.js';
+import { messageOf } from '../utils/text.js';
+import { listenerOf, PassedTimeout, withinTime } from './deadline.js';
+import { callFiles } from './hooks.js';
 export const everySession = '*';
 export const conversationMethods = {
     sessions: 'cmod:sessions',
@@ -27,10 +32,11 @@ export const conversationMethods = {
     changed: 'cmod:changed',
     before: 'cmod:before',
 };
-const actPermissions = { send: 'prompt', startTask: 'tasks', usage: 'conversation', clients: 'conversation' };
+const actPermissions = { send: 'prompt', startTask: 'tasks', usage: 'conversation', surfaces: 'conversation', abort: 'prompt' };
 const startsTurns = ['CronCreate'];
 const ownSchedule = ['CronDelete', 'CronList'];
-export const beforePermission = (event) => (event === 'toolCall' ? 'tools' : event === TaskStart || event === TaskEnd ? 'tasks' : 'prompt');
+export const beforePermission = (event) => (event === 'toolCall' ? 'tools' : event === TaskStart ? 'tasks' : 'prompt');
+const methodOf = (prefix, event) => `${prefix}${Object.entries(sessionEvents).find(([, each]) => each === event)?.[0] ?? event}`;
 export const isAct = (action) => action === 'callTool' || action in actPermissions;
 export function toolPermission(tool) {
     return startsTurns.includes(tool) ? 'prompt' : ownSchedule.includes(tool) ? undefined : 'tools';
@@ -38,11 +44,10 @@ export function toolPermission(tool) {
 export function actPermission(action, input) {
     return action === 'callTool' ? (toolPermission(String(input?.name)) ?? 'tools') : actPermissions[action];
 }
-const asked = (action) => `cmod: ${action} runs only on a session's own main loop, and Claude Code gives a subagent's tasks no way to start a task or run a tool.`;
 export async function usageOf(claude) {
     const [model, usage] = await Promise.all([claude.session.model(), claude.session.usage()]);
     const { tokens, window, percent } = usage.context;
-    return { model, context: { ...(tokens === undefined ? {} : { tokens }), window, ...(percent === undefined ? {} : { percent }) }, ...(usage.cost === undefined ? {} : { cost: { usd: usage.cost.usd } }) };
+    return { model, contextWindow: { ...(tokens === undefined ? {} : { tokenCount: tokens }), size: window, ...(percent === undefined ? {} : { percent }) }, ...(usage.cost === undefined ? {} : { cost: { usd: usage.cost.usd } }) };
 }
 export function payloadOf(change) {
     if (change.type === Message)
@@ -96,10 +101,10 @@ export function isInScope(scope, session, change, isUnder) {
     if (scope.session !== undefined && scope.session !== session)
         return false;
     const task = taskOfChange(change);
+    if (scope.isAgent === true)
+        return (change.type === TaskStart || change.type === TaskEnd ? change.task.parent : task) === scope.task;
     if (scope.task !== undefined && (task === undefined || !isUnder(task, scope.task)))
         return false;
-    if (scope.isGoal === true && change.type !== GoalChange && change.type !== TaskStart && (task === undefined || task === scope.task))
-        return false;
     if (scope.context !== undefined && (contextOfChange(change) !== scope.context || ownerOfChange(change) !== scope.task))
         return false;
     if (scope.turn === undefined)
@@ -108,7 +113,7 @@ export function isInScope(scope, session, change, isUnder) {
         return change.message.turn === scope.turn;
     return (change.type === TurnStart || change.type === TurnEnd) && change.turn.prompt.id === scope.turn;
 }
-export function createSessionsClient({ name, claude, report, isGranted }) {
+export function createSessionsClient({ name, claude, report, isGranted, hookOn, routeOn }) {
     const call = (method, input) => claude.cmod.call({ to: cmodPluginName, method, input });
     const listening = new Map();
     const deciding = new Map();
@@ -149,11 +154,9 @@ export function createSessionsClient({ name, claude, report, isGranted }) {
         if (change.type === TaskStart)
             parents.get(session)?.set(change.task.id, change.task.parent);
     };
-    const add = (into, scope, event, matcherOrListener, maybeListener, onChange) => {
-        const listener = (maybeListener ?? matcherOrListener);
-        const matcher = maybeListener === undefined ? undefined : matcherOrListener;
+    const add = (into, scope, event, method, args, onChange) => {
         const key = keyOf(scope);
-        const entry = { scope, event, matcher, listener };
+        const entry = { scope, event, method, ...listenerOf(name, method, args) };
         const set = into.get(key) ?? new Set();
         set.add(entry);
         into.set(key, set);
@@ -181,31 +184,74 @@ export function createSessionsClient({ name, claude, report, isGranted }) {
                 return undefined;
             if (entry.matcher !== undefined && !matches(payloadOf(latest), entry.matcher))
                 return undefined;
-            const answer = await entry.listener(payloadFor(session, latest));
-            if (answer === undefined || isGranted(beforePermission(event)))
+            const payload = await payloadFor(session, latest);
+            const answer = await withinTime(claude.clock, entry.method, entry.options, (time) => entry.listener(payload, time)).catch((error) => {
+                if (entry.options.onFailure !== 'refuse')
+                    throw error;
+                report(`session:${entry.method}`, `The ${entry.method} listener failed`, error);
+                return { refuse: `${name}: ${messageOf(error)}` };
+            });
+            if (answer === undefined || answer === null || (typeof answer === 'object' && 'refuse' in answer) || isGranted(beforePermission(event)))
                 return answer;
-            throw new Error(`Its before(${event}) answer changes nothing until ${beforePermission(event)} is turned on for ${name} in /mods.`);
+            throw new Error(`Its ${entry.method} answer changes nothing until ${beforePermission(event)} is turned on for ${name} in /mods.`);
         });
-        return foldAnswers(event, change, askers, (error) => report(`before:${event}`, `The before(${event}) listener failed`, error));
+        return foldAnswers(event, change, askers, (error) => report(`session:${methodOf('before', event)}`, `The ${methodOf('before', event)} listener failed`, error));
+    };
+    const eventMethods = (scopeOf, hasBefore, ended) => {
+        const method = (into, named, event) => (...args) => {
+            if (ended !== undefined)
+                throw new Error(`${name}: ${ended} has ended, so its ${named} never fires. Listen on its Session.`);
+            return add(into, scopeOf(), event, named, args, subscribe);
+        };
+        return Object.fromEntries([
+            ...Object.entries(sessionEvents).map(([named, event]) => [`on${named}`, method(listening, `on${named}`, event)]),
+            ...(hasBefore ? beforeEvents.map((named) => [`before${named}`, method(deciding, `before${named}`, sessionEvents[named])]) : []),
+        ]);
     };
-    const recordPart = (scope) => ({
-        search: (text, options = {}) => call(conversationMethods.search, { text, ...scope, ...optionsOf(options) }),
-        on: (event, matcherOrListener, maybeListener) => add(listening, scope, event, matcherOrListener, maybeListener, subscribe),
-        before: (event, matcherOrListener, maybeListener) => add(deciding, scope, event, matcherOrListener, maybeListener, subscribe),
+    const withFiles = async (message) => {
+        if (message.type !== ToolCall && message.type !== ToolResult)
+            return message;
+        return { ...message, files: await callFiles(name, claude, { tool: message.name, input: message.input }, message.cwd) };
+    };
+    const messagesFrom = async (method, input) => Promise.all((await call(method, input)).map(withFiles));
+    const searched = (request, matcher) => ({
+        async *[Symbol.asyncIterator]() {
+            let before = request['before'];
+            for (;;) {
+                const page = await messagesFrom(conversationMethods.search, { ...request, ...(before === undefined ? {} : { before }) });
+                for (const message of page)
+                    if (matcher === undefined || matches(message, matcher))
+                        yield message;
+                const last = page.at(-1);
+                if (last === undefined || page.length < searchLimit)
+                    return;
+                before = { session: last.session, id: last.id };
+            }
+        },
+    });
+    const recordPart = (scope, ended) => ({
+        search: (text, matcher) => searched({ text, ...scope }, matcher),
+        ...eventMethods(() => scope, true, ended),
     });
     const turnOf = (scope, data) => {
         const task = data.prompt.task ?? scope.task;
         return {
             ...data,
-            ...recordPart({ ...scope, ...(task === undefined ? {} : { task }), turn: data.prompt.id }),
-            messages: () => call(conversationMethods.messages, { session: scope.session, turn: data.prompt.id, ...(task === undefined ? {} : { task }) }),
+            ...recordPart({ ...scope, ...(task === undefined ? {} : { task }), turn: data.prompt.id }, data.closedAt === undefined ? undefined : `turn ${data.prompt.id}`),
+            messages: () => messagesFrom(conversationMethods.messages, { session: scope.session, turn: data.prompt.id, ...(task === undefined ? {} : { task }) }),
+            abort: async () => {
+                if (data.closedAt !== undefined)
+                    throw new Error(`${name}: turn ${data.prompt.id} has ended, so there is nothing to abort.`);
+                const session = scope.session ?? current.id;
+                await act(session, 'abort', { turn: data.prompt.id }, task === undefined ? undefined : { session, task });
+            },
         };
     };
     const contextOf = (scope, data) => {
         const owned = { ...(scope.session === undefined ? {} : { session: scope.session }), ...(data.task === undefined ? {} : { task: data.task }) };
         return {
             ...data,
-            ...recordPart({ ...owned, context: data.number }),
+            ...recordPart({ ...owned, context: data.number }, data.closedAt === undefined ? undefined : `context ${data.number}`),
             turns: async () => (await call(conversationMethods.turns, { ...owned, context: data.number })).map((turn) => turnOf(owned, turn)),
         };
     };
@@ -218,22 +264,27 @@ export function createSessionsClient({ name, claude, report, isGranted }) {
         owner: ownerOf(session, data),
         ...recordPart({ session, task: data.id }),
         tasks: async () => (await call(conversationMethods.tasks, { session, task: data.id })).map((task) => taskOf(session, task)),
-        messages: () => call(conversationMethods.messages, { session, task: data.id }),
+        messages: () => messagesFrom(conversationMethods.messages, { session, task: data.id }),
     });
-    const goalOf = (scope, data) => ({
-        ...data,
-        ...recordPart({ ...scope, isGoal: true }),
-        tasks: async () => (await call(conversationMethods.tasks, { session: scope.session, ...(scope.task === undefined ? {} : { task: scope.task }) })).map((task) => taskOf(scope.session ?? current.id, task)),
+    const goalOf = (where) => ({
+        search: (text, matcher) => searched({ text, ...where() }, matcher),
+        ...eventMethods(() => ({ ...where(), isGoal: true }), true),
+        text: async () => (await call(conversationMethods.goal, where())).text,
+        tasks: async () => {
+            const { session = current.id, task } = where();
+            return (await call(conversationMethods.tasks, { session, ...(task === undefined ? {} : { task }) })).map((each) => taskOf(session, each));
+        },
         update: async ({ text }) => {
             if (text.trim() === '')
                 throw new Error(`${name}: a goal needs text.`);
-            await call(conversationMethods.updateGoal, { session: scope.session ?? current.id, ...(scope.task === undefined ? {} : { task: scope.task }), text });
+            const { session = current.id, task } = where();
+            await call(conversationMethods.updateGoal, { session, ...(task === undefined ? {} : { task }), text });
         },
     });
-    const payloadFor = (session, change) => {
+    const payloadFor = async (session, change) => {
         const scope = { session };
         if (change.type === Message)
-            return change.message;
+            return withFiles(change.message);
         if ('turn' in change)
             return turnOf(scope, change.turn);
         if ('context' in change)
@@ -242,7 +293,8 @@ export function createSessionsClient({ name, claude, report, isGranted }) {
             return taskOf(session, change.task);
         if ('usage' in change)
             return change.usage;
-        return goalOf({ session, ...(change.goal.task === undefined ? {} : { task: change.goal.task }) }, { text: change.goal.text });
+        const { task } = change.goal;
+        return goalOf(() => ({ session, ...(task === undefined ? {} : { task }) }));
     };
     const act = (session, action, input, owned) => call(conversationMethods.act, { session: owned?.session ?? session, action, input, ...(owned === undefined ? {} : { task: owned.task }) });
     const sendHere = async ({ type, text, as }) => {
@@ -258,26 +310,15 @@ export function createSessionsClient({ name, claude, report, isGranted }) {
         if ('drop' in submitted && typeof submitted.drop === 'string')
             throw new Error(`${name}: Claude Code dropped the prompt: ${submitted.drop}`);
     };
-    const startHere = async (task) => {
-        const started = await claude.agent.spawn({
-            prompt: task.prompt,
-            ...(task.name === undefined ? {} : { description: task.name, name: task.name }),
-            ...(task.agentType === undefined ? {} : { subagentType: task.agentType }),
-            ...(task.model === undefined ? {} : { model: task.model }),
-            ...(task.cwd === undefined ? {} : { cwd: task.cwd }),
-        });
-        if (started.deny !== undefined)
-            throw new Error(`${name}: Claude Code refused the task: ${started.deny}`);
-        return taskOf(current.id, { id: started.agentId ?? '', title: task.name ?? '', agentType: task.agentType ?? 'general-purpose', model: started.model, openedBy: '', openedAt: new Date().toISOString() });
-    };
-    const clientsHere = async () => [...(await claude.session.surfaces())];
+    const startHere = async (task) => taskOf(current.id, await spawnTask(claude, task).catch((error) => Promise.reject(new Error(`${name}: ${messageOf(error)}`))));
+    const surfacesHere = async () => [...(await claude.session.surfaces())];
     const sessionOf = (read, owned) => {
         const id = () => read().id;
         const isHere = () => owned === undefined && id() === current.id;
-        const scope = () => (owned === undefined ? { session: id() } : { session: owned.session, task: owned.task });
+        const scope = () => (owned === undefined ? { session: id(), isAgent: true } : { session: owned.session, task: owned.task, isAgent: true });
         const where = () => (owned === undefined ? { session: id() } : { session: owned.session, task: owned.task });
-        const turnsOf = async (options = {}) => (await call(conversationMethods.turns, { ...where(), ...options })).map((turn) => turnOf(scope(), turn));
-        const contextsOf = async () => (await call(conversationMethods.contexts, where())).map((context) => contextOf(scope(), context));
+        const turnsOf = async (options = {}) => (await call(conversationMethods.turns, { ...where(), ...options })).map((turn) => turnOf(where(), turn));
+        const contextsOf = async () => (await call(conversationMethods.contexts, where())).map((context) => contextOf(where(), context));
         const session = {
             get id() {
                 return read().id;
@@ -309,10 +350,9 @@ export function createSessionsClient({ name, claude, report, isGranted }) {
             get forkedFrom() {
                 return read().forkedFrom;
             },
-            search: (text, options = {}) => recordPart(scope()).search(text, options),
-            on: (event, matcherOrListener, maybeListener) => recordPart(scope()).on(event, matcherOrListener, maybeListener),
-            before: (event, matcherOrListener, maybeListener) => recordPart(scope()).before(event, matcherOrListener, maybeListener),
-            goal: async () => goalOf(scope(), await call(conversationMethods.goal, where())),
+            search: (text, matcher) => recordPart(scope()).search(text, matcher),
+            ...eventMethods(scope, true),
+            goal: goalOf(where),
             context: async () => {
                 const all = await contextsOf();
                 const last = all.at(-1);
@@ -326,9 +366,9 @@ export function createSessionsClient({ name, claude, report, isGranted }) {
                 return last?.closedAt === undefined ? last : undefined;
             },
             turns: turnsOf,
-            messages: (options = {}) => call(conversationMethods.messages, { ...where(), ...options }),
+            messages: (options = {}) => messagesFrom(conversationMethods.messages, { ...where(), ...options }),
             usage: async () => (isHere() ? usageOf(claude) : act(id(), 'usage', null, owned)),
-            clients: async () => (isHere() ? clientsHere() : act(id(), 'clients', null, owned)),
+            surfaces: async () => (isHere() ? surfacesHere() : act(id(), 'surfaces', null, owned)),
             async send(message) {
                 if (message.text.trim() === '')
                     throw new Error(`${name}: send needs text.`);
@@ -336,21 +376,18 @@ export function createSessionsClient({ name, claude, report, isGranted }) {
                     return sendHere(message);
                 await act(id(), 'send', message, owned);
             },
+        };
+        if (owned !== undefined)
+            return session;
+        return Object.assign(session, {
             async startTask(task) {
-                if (owned !== undefined)
-                    throw new Error(asked('startTask'));
                 if (isHere())
                     return startHere(task);
                 const started = await act(id(), 'startTask', task);
                 return taskOf(id(), started);
             },
-            async callTool(toolCall) {
-                if (owned !== undefined)
-                    throw new Error(asked('callTool'));
-                return act(id(), 'callTool', toolCall);
-            },
-        };
-        return session;
+            callTool: async (toolCall) => (await withFiles(await act(id(), 'callTool', toolCall))),
+        });
     };
     const ownerOf = (session, data) => {
         const parent = session === current.id ? current : known.get(session);
@@ -366,9 +403,113 @@ export function createSessionsClient({ name, claude, report, isGranted }) {
             lastAt: data.closedAt ?? data.openedAt,
         }), { session, task: data.id });
     };
-    const currentSession = sessionOf(() => current);
-    const every = recordPart({});
-    const answerBefore = async (session, event, change, isInProject) => (isGranted('conversation') ? combined(session, event, change, isInProject) : undefined);
+    const processListeners = new Map();
+    const raise = async (method, payload) => {
+        const isBefore = method.startsWith('before');
+        const heard = [...(processListeners.get(method) ?? [])].filter(({ matcher }) => payload['task'] === undefined && (matcher === undefined || matches(payload, matcher)));
+        if (!isBefore) {
+            await Promise.all(heard.map(({ listener, options }) => withinTime(claude.clock, method, options, (time) => listener(payload, time)).catch((error) => {
+                if (!(error instanceof PassedTimeout))
+                    report(`session:${method}`, `The ${method} listener failed`, error);
+            })));
+            return undefined;
+        }
+        const takes = answerKeys[method.slice('before'.length)] ?? [];
+        let merged;
+        for (const { listener, options } of heard) {
+            try {
+                const answer = (await withinTime(claude.clock, method, options, (time) => listener(payload, time)));
+                if (answer === undefined || answer === null)
+                    continue;
+                const unread = Object.keys(answer).filter((key) => !takes.includes(key));
+                if (unread.length > 0)
+                    throw new Error(`it answered ${unread.join(' and ')}, which ${method} does not take. It takes ${takes.map((key) => `{ ${key} }`).join(', ') || 'no answer'}.`);
+                const notes = [merged?.['note'], answer['note']].filter((note) => typeof note === 'string');
+                merged = { ...merged, ...answer, ...(notes.length === 0 ? {} : { note: notes.join('\n\n') }) };
+                if (typeof answer['refuse'] === 'string')
+                    return merged;
+            }
+            catch (error) {
+                report(`session:${method}`, `The ${method} listener failed`, error);
+                if (options.onFailure === 'refuse' || method === 'beforePermissionRequest')
+                    return { refuse: `${name}: ${messageOf(error)}` };
+            }
+        }
+        return merged;
+    };
+    const permissionCheck = (e, below) => ({ session: current.id, cwd: current.cwd, ...defined({ task: e.agentId, callId: e.tool_use_id, reason: below.reason, rule: below.rule, ceiling: e.ceiling === undefined ? undefined : verdictName(e.ceiling) }), name: e.tool, input: recordOf(e.input), decision: verdictName(below.decision) });
+    const commandRun = async (e) => {
+        const source = (await claude.command.list()).find((command) => command.name === e.command)?.source;
+        return { session: current.id, cwd: current.cwd, name: e.command, args: e.args, ...defined({ source }), from: senderOf(e.origin, false) };
+    };
+    const commandListeners = { beforeRun: new Set(), onRun: new Set() };
+    for (const [method, held] of Object.entries(commandListeners))
+        processListeners.set(method, held);
+    routeOn?.('command.run', async (e, next) => {
+        if (commandListeners.beforeRun.size === 0 && commandListeners.onRun.size === 0)
+            return next(e);
+        const run = await commandRun(e);
+        const answer = commandListeners.beforeRun.size === 0 ? undefined : await raise('beforeRun', run);
+        if (typeof answer?.['refuse'] === 'string')
+            return { text: answer['refuse'] };
+        const changes = answer !== undefined && isGranted('prompt') ? answer : undefined;
+        if (answer !== undefined && changes === undefined)
+            report('session:beforeRun', 'The beforeRun listener failed', new Error(`${name}: its answer changes a command, which needs the prompt permission.`));
+        if (typeof changes?.['result'] === 'string')
+            return { text: changes['result'], ...(typeof changes['exitCode'] === 'number' ? { exitCode: changes['exitCode'] } : {}) };
+        const args = typeof changes?.['args'] === 'string' ? changes['args'] : e.args;
+        const ran = await next(args === e.args ? e : { ...e, args });
+        void raise('onRun', { ...run, args });
+        return typeof changes?.['note'] === 'string' ? { ...ran, context: [...(ran.context ?? []), changes['note']] } : ran;
+    });
+    const listenTo = (method, named) => {
+        if (hookOn === undefined || routeOn === undefined)
+            throw new Error(`${name}: ${method} works only in a mod's own session.`);
+        const isBefore = method.startsWith('before');
+        if (named === 'PermissionCheck') {
+            return routeOn('tool.check', async (e, next) => {
+                const below = (await next(e));
+                if (!isBefore) {
+                    void raise(method, permissionCheck(e, below));
+                    return below;
+                }
+                const answer = await raise(method, permissionCheck(e, below));
+                if (answer === undefined || below.decision === 'deny')
+                    return below;
+                if (typeof answer['refuse'] === 'string')
+                    return { decision: 'deny', reason: answer['refuse'] };
+                if (typeof answer['ask'] === 'string')
+                    return { decision: 'ask', reason: answer['ask'] };
+                return answer['allow'] === true ? { decision: 'allow' } : below;
+            });
+        }
+        const event = processEvents[named];
+        const hook = (isBefore ? event.before : undefined) ?? event.on;
+        return hookOn(hook, async (input) => {
+            const payload = processPayloadOf(named, input);
+            if (!isBefore) {
+                if (named !== 'SessionStart' || payload['source'] !== 'compact')
+                    void raise(method, payload);
+                return undefined;
+            }
+            const answer = await raise(method, payload);
+            return answer === undefined ? undefined : hookAnswerOf(named, hook, answer);
+        });
+    };
+    const listen = (method, args) => {
+        const entry = listenerOf(name, method, args);
+        const held = processListeners.get(method) ?? new Set();
+        if (!processListeners.has(method)) {
+            listenTo(method, method.replace(/^(on|before)/, ''));
+            processListeners.set(method, held);
+        }
+        held.add(entry);
+        return { dispose: () => void held.delete(entry) };
+    };
+    const processMethods = () => Object.fromEntries(Object.entries(processEvents).flatMap(([named, event]) => [`on${named}`, ...('before' in event ? [`before${named}`] : [])]).map((method) => [method, (...args) => listen(method, args)]));
+    const currentSession = Object.assign(sessionOf(() => current), processMethods());
+    const every = eventMethods(() => ({}), false);
+    const answerBefore = async (session, event, change, isInProject) => (session === current.id || isGranted('conversation') ? combined(session, event, change, isInProject) : undefined);
     return {
         sessions: {
             get current() {
@@ -383,23 +524,27 @@ export function createSessionsClient({ name, claude, report, isGranted }) {
                     current = { ...current, title: data.title };
                 return currentSession;
             }),
-            search: (text, options = {}) => call(conversationMethods.search, { text, ...optionsOf(options), ...(options.running === undefined ? {} : { running: options.running }), ...(options.since === undefined ? {} : { since: options.since }), ...(options.everyProject === undefined ? {} : { everyProject: options.everyProject }) }),
-            on: every.on,
-            before: every.before,
+            search: (text, matcher, options = {}) => searched({ text, ...searchOptionsOf(options) }, matcher),
+            ...every,
         },
         changed(session, change, isInProject) {
             remember(session, change);
             for (const key of isInProject ? [session, everySession] : [session]) {
-                for (const { scope, event, matcher, listener } of listening.get(key) ?? []) {
+                for (const { scope, event, method, matcher, listener, options } of listening.get(key) ?? []) {
                     if (!isHeardBy(event, matcher, change) || !isInScope(scope, session, change, isUnderIn(session)))
                         continue;
-                    void Promise.resolve()
-                        .then(() => listener(payloadFor(session, change)))
-                        .catch((error) => report(`session:${event}`, `The ${event} listener failed`, error));
+                    void payloadFor(session, change)
+                        .then((payload) => withinTime(claude.clock, method, options, (time) => listener(payload, time)))
+                        .catch((error) => {
+                        if (!(error instanceof PassedTimeout))
+                            report(`session:${method}`, `The ${method} listener failed`, error);
+                    });
                 }
             }
         },
         answerBefore,
+        raise,
+        listen,
         follow(next) {
             const moved = next.id !== current.id && current.id !== '';
             const previous = current.id;
@@ -422,12 +567,128 @@ export function createSessionsClient({ name, claude, report, isGranted }) {
         },
     };
 }
-export function resultOf(where, answered) {
-    const base = { id: '', type: ToolResult, at: new Date().toISOString(), session: where.session, context: where.context, ...(where.turn === undefined ? {} : { turn: where.turn.prompt.id }), callId: '' };
+const verdictName = (decision) => (decision === 'deny' ? 'refuse' : decision);
+const recordOf = (value) => (typeof value === 'object' && value !== null && !Array.isArray(value) ? value : {});
+const defined = (fields) => Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined));
+const placementOf = (input) => defined({ session: input['session_id'], task: input['agent_id'], agentType: input['agent_type'], cwd: input['cwd'], permissionMode: input['permission_mode'] });
+const mcpServerOf = (server) => (server === undefined ? undefined : { name: String(recordOf(server)['name']), source: String(recordOf(server)['source']) });
+const modelChangeOf = (input) => ({
+    model: input['to_model'],
+    previous: input['from_model'],
+    requested: input['requested_model'] ?? undefined,
+    source: input['source'],
+    contextTokenCount: input['context_tokens'],
+    isCacheWarm: input['prompt_cache_warm'],
+    cacheTtl: input['cache_ttl'],
+    cacheWriteUsd: input['estimated_cache_write_usd'],
+    pricing: input['pricing'],
+});
+const answerKeys = {
+    Run: ['args', 'note', 'result', 'exitCode', 'refuse'],
+    ProjectSetup: [],
+    SessionStart: ['note', 'title', 'reloadSkills', 'firstPrompt'],
+    ModelChange: ['ask', 'refuse'],
+    WorktreeCreate: ['result'],
+    Elicitation: ['refuse'],
+    ElicitationResponse: ['refuse'],
+    PermissionCheck: ['allow', 'ask', 'refuse'],
+    PermissionRequest: ['allow', 'input', 'updates', 'refuse', 'interrupt'],
+    PermissionDenial: ['retry'],
+    ToolBatch: ['note'],
+    TodoCreate: ['refuse'],
+    TodoComplete: ['refuse'],
+    ReplyDisplay: ['text'],
+};
+const todoOf = (input) => ({ id: input['task_id'], subject: input['task_subject'], description: input['task_description'], teammate: input['teammate_name'] });
+const processFields = {
+    ProjectSetup: (input) => ({ trigger: input['trigger'] }),
+    SessionStart: (input) => ({
+        source: input['source'],
+        model: input['model'],
+        title: input['session_title'] || undefined,
+        idleSeconds: input['seconds_since_last_response'],
+        contextTokenCount: input['context_tokens'],
+        isCacheWarm: input['prompt_cache_likely_expired'] === undefined ? undefined : input['prompt_cache_likely_expired'] !== true,
+        cacheWriteUsd: input['estimated_cache_write_usd'],
+    }),
+    SessionEnd: (input) => ({ reason: input['reason'] === 'prompt_input_exit' ? 'exit' : input['reason'] }),
+    ModelChange: modelChangeOf,
+    CwdChange: (input) => ({ cwd: input['new_cwd'] ?? input['cwd'], previous: input['old_cwd'] }),
+    DirectoryAdd: (input) => ({ directory: input['directory'], source: input['source'] === 'slash_command' ? 'command' : 'sdk' }),
+    WorktreeCreate: (input) => ({ name: input['name'] }),
+    WorktreeRemove: (input) => ({ path: input['worktree_path'] }),
+    Notification: (input) => ({ text: input['message'], title: input['title'], type: input['notification_type'] }),
+    Elicitation: (input) => ({ id: input['elicitation_id'], server: input['mcp_server_name'], text: input['message'], mode: input['mode'], url: input['url'], schema: input['requested_schema'] }),
+    ElicitationResponse: (input) => ({ id: input['elicitation_id'], server: input['mcp_server_name'], mode: input['mode'], action: input['action'], content: input['content'] }),
+    PermissionRequest: (input) => ({ name: input['tool_name'], input: recordOf(input['tool_input']), suggestions: input['permission_suggestions'] ?? [], mcpServer: mcpServerOf(input['mcp_server']) }),
+    PermissionDenial: (input) => ({ name: input['tool_name'], input: recordOf(input['tool_input']), callId: input['tool_use_id'], reason: input['reason'], mcpServer: mcpServerOf(input['mcp_server']) }),
+    ToolBatch: (input) => ({
+        calls: (Array.isArray(input['tool_calls']) ? input['tool_calls'] : []).map((call) => {
+            const fields = recordOf(call);
+            return defined({ callId: fields['tool_use_id'], name: fields['tool_name'], input: recordOf(fields['tool_input']), output: fields['tool_response'] });
+        }),
+    }),
+    TodoCreate: todoOf,
+    TodoComplete: todoOf,
+    ReplyDisplay: (input) => ({ replyId: input['message_id'], index: input['index'], isLast: input['final'], text: input['delta'] }),
+};
+export async function spawnTask(claude, task) {
+    if (task.title.trim() === '')
+        throw new Error('a task needs a title.');
+    const started = await claude.agent.spawn({
+        prompt: task.prompt,
+        description: task.title,
+        ...(task.name === undefined ? {} : { name: task.name }),
+        ...(task.agentType === undefined ? {} : { subagentType: task.agentType }),
+        ...(task.model === undefined ? {} : { model: task.model }),
+        ...(task.cwd === undefined ? {} : { cwd: task.cwd }),
+    });
+    if (started.deny !== undefined)
+        throw new Error(`Claude Code refused the task: ${started.deny}`);
+    if (started.agentId === undefined)
+        throw new Error('Claude Code answered without starting a task.');
+    return { id: started.agentId, title: task.title, agentType: task.agentType ?? 'general-purpose', model: started.model, openedBy: '', openedAt: new Date().toISOString() };
+}
+export function processPayloadOf(named, input) {
+    const fields = recordOf(input);
+    return { ...placementOf(fields), ...defined(processFields[named](fields)) };
+}
+export function hookAnswerOf(named, hook, answer) {
+    const output = (fields) => ({ hookSpecificOutput: { hookEventName: hook, ...defined(fields) } });
+    const refuse = typeof answer['refuse'] === 'string' ? answer['refuse'] : undefined;
+    if (named === 'SessionStart')
+        return output({ additionalContext: answer['note'], sessionTitle: answer['title'], reloadSkills: answer['reloadSkills'], initialUserMessage: answer['firstPrompt'] });
+    if (named === 'ModelChange') {
+        if (refuse !== undefined)
+            return output({ permissionDecision: 'deny', permissionDecisionReason: refuse });
+        return typeof answer['ask'] === 'string' ? output({ permissionDecision: 'ask', permissionDecisionReason: answer['ask'] }) : undefined;
+    }
+    if (named === 'WorktreeCreate')
+        return output({ worktreePath: answer['result'] });
+    if (named === 'PermissionRequest') {
+        if (refuse !== undefined)
+            return output({ decision: defined({ behavior: 'deny', message: refuse, interrupt: answer['interrupt'] }) });
+        return answer['allow'] === true ? output({ decision: defined({ behavior: 'allow', updatedInput: answer['input'], updatedPermissions: answer['updates'] }) }) : undefined;
+    }
+    if (named === 'PermissionDenial')
+        return output({ retry: answer['retry'] });
+    if (named === 'ToolBatch')
+        return output({ additionalContext: answer['note'] });
+    if (named === 'ReplyDisplay')
+        return output({ displayContent: answer['text'] });
+    return refuse === undefined ? undefined : { decision: 'block', reason: refuse };
+}
+export function resultOf(where, call, answered) {
+    const base = { id: '', type: ToolResult, at: new Date().toISOString(), session: where.session, context: where.context, ...(where.turn === undefined ? {} : { turn: where.turn.prompt.id }), callId: '', name: call.name, input: call.input, cwd: call.cwd, files: noFiles };
     if (answered.deny !== undefined)
-        return { ...base, text: answered.deny, isError: true };
-    return { ...base, text: answered.text ?? JSON.stringify(answered.result), isError: answered.isError === true };
+        return { ...base, output: answered.deny, isError: true };
+    return { ...base, output: answered.result ?? answered.text, isError: answered.isError === true };
 }
-function optionsOf(options) {
-    return { ...(options.limit === undefined ? {} : { limit: options.limit }), ...(options.before === undefined ? {} : { before: { session: options.before.session, id: options.before.id } }) };
+function searchOptionsOf({ running, since, everyProject, before }) {
+    return {
+        ...(running === undefined ? {} : { running }),
+        ...(since === undefined ? {} : { since }),
+        ...(everyProject === undefined ? {} : { everyProject }),
+        ...(before === undefined ? {} : { before: { session: before.session, id: before.id } }),
+    };
 }

package/runtime/tool-calls.d.ts

@@ -6,7 +6,6 @@ export type Agent = {
 };
 export type ToolCalls = {
     agentOf(toolUseId: string | undefined): Promise<Agent>;
-    cwdOf(toolUseId: string): string | undefined;
 };
 export declare const reservedKeys: readonly string[];
 export declare function toolInputOf(envelope: object): Record<string, unknown>;

package/runtime/tool-calls.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-calls.d.ts","sourceRoot":"","sources":["../src/runtime/tool-calls.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEzC,MAAM,MAAM,KAAK,GAAG;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAE5D,MAAM,MAAM,SAAS,GAAG;IACtB,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,CAAA;IACtD,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;CAC7C,CAAA;AAED,eAAO,MAAM,YAAY,EAAE,SAAS,MAAM,EAAkD,CAAA;AAE5F,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAErE;AAMD,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,CA8CnE"}
+{"version":3,"file":"tool-calls.d.ts","sourceRoot":"","sources":["../src/runtime/tool-calls.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEzC,MAAM,MAAM,KAAK,GAAG;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAE5D,MAAM,MAAM,SAAS,GAAG;IACtB,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,CAAA;CACvD,CAAA;AAED,eAAO,MAAM,YAAY,EAAE,SAAS,MAAM,EAAkD,CAAA;AAE5F,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAErE;AAID,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,CA8BnE"}