@adecore/agents 0.23.0 → 0.24.0

package/src/chat/chat-core.ts

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import {
     ChatAttachmentUploadsSchema,
     generatedImageAttachment,
+    HOST_TASK_ORIGIN,
     type AgentKind,
     type ChatAttachment,
     type ChatAttachResult,
@@ -13,6 +14,7 @@ import {
     type ChatCreatePayload,
     type ChatEvent,
     type ChatHistoryResult,
+    type ChatGoalAction,
     type ChatInfo,
     type ChatItem,
     type ChatQueuedMessage,
@@ -102,6 +104,57 @@ const DEFAULT_RESUME_WORDS: ResumeWords = {
     preamble: null
 };
 
+/*
+ * What a host adds to its chats. Every hook may be left out, and does nothing without it; none of them
+ * knows the client, so a check of who asks belongs on the wire.
+ */
+export interface ChatCoreHooks {
+    /* Throws for a folder this chat may not start in; asked every time a chat is loaded, from disk too. */
+    admit?(chatId: string, cwd: string): Promise<void>;
+    /* The model a new chat starts on when the host already knows; the explicit one still wins. */
+    openingSelection?(chatId: string, kind: AgentKind): ModelSelection | undefined;
+    /* The mode a chat runs in, which a host may narrow whatever its record or its client says. */
+    runtimeModeFor?(chatId: string, mode: RuntimeMode): RuntimeMode;
+    /* What the agent is told once at the start of every process of this chat, in place of `instructions`; null for nothing. */
+    instructionsFor?(chatId: string): string | null;
+    /* What of the instructions a resumed thread hears again in front of its next prompt, for a CLI that ignores them on a resume. */
+    resumeNoteFor?(chatId: string): string | null;
+    /*
+     * Folders outside its working directory a chat's agent may reach without asking, absolute. Asked
+     * before every turn, so a host can hand one over for as long as it is needed: a change starts the
+     * next turn in a new process that resumes the thread, and never cuts a turn in flight.
+     */
+    foldersFor?(chatId: string): readonly string[];
+    /* Whether no list of chats shows this one, which `ChatInfo.hidden` says to every client. */
+    hiddenFor?(chatId: string): boolean;
+    /* What the host says in front of a chat's next real prompt, beside what the chat keeps itself. */
+    promptNotesFor?(chatId: string): PromptNotes | undefined;
+    /* How the chats a person attached to a message are named to the agent; without it they are dropped. */
+    referencesFor?(chatId: string): ChatReferences | undefined;
+    /* The environment of this chat's CLI before its account adds its own. */
+    envFor?(chatId: string, base: Record<string, string>): Record<string, string | undefined>;
+    /* A chat just loaded or made, its stored turns settled; whatever the host lays down in it goes here. */
+    opened?(session: ChatSession, stored: ChatRecord | null): Promise<void>;
+    /* What the host keeps in the chat's record beside the thread. */
+    recordExtras?(chatId: string): ChatRecordExtras;
+    /* A clear is about to start; it waits for this. */
+    clearing?(chatId: string): Promise<void>;
+    /* The chat was cleared; what runs before the first await is in the record written right after. */
+    cleared?(chatId: string): Promise<void>;
+    /* The chat left memory for good, before its files go. */
+    forgotten?(chatId: string): void;
+    /* The chat was removed; what the host keeps of it goes along. */
+    removed?(chatId: string, chat: { info: ChatInfo; items: ChatItem[] }): Promise<void>;
+    /* An event of a chat went out, after the observers and before the clients reading its thread. */
+    broadcasted?(chatId: string, event: ChatEvent): void;
+    /* When whoever opened this chat stopped it; a turn from before that is never taken up again. */
+    endedAt?(chatId: string): number | null;
+    /* Why a turn the host went down in stays down when `onInterruptedRun` says no, in the words of the note it ends with. */
+    unownedReason?(chatId: string): string;
+    /* How a turn the host went down in is taken up in this chat. */
+    resumeWords?(chatId: string): Promise<ResumeWords>;
+}
+
 export interface ChatCoreOptions {
     intelligentUi?: ChatUiHost;
     // The info string that marks a UI fence in a reply, for a host that keeps a name of its own.
@@ -132,7 +185,7 @@ export interface ChatCoreOptions {
     // What a running turn says about the plan its CLI runs on; the usage monitor takes it from here.
     onLimits?: (update: LimitsUpdate) => void;
     // Where Claude Code's own name for a session is read, in the projects folder of the chat's account; the other CLIs write none down.
-    claudeTitles?: { forSession(agentSessionId: string, projectsDir: string): Promise<string | null> };
+    claudeTitles?: { forSession(agentSessionId: string, projectsDir: string, cwd: string): Promise<string | null> };
     // A name for a Codex chat, asked of a one-shot CLI: its app-server names no thread on its own.
     nameChat?: (provider: AgentKind, input: ChatTitleInput) => Promise<string | null>;
     // Where a subagent's whole conversation is read and how its growth is noticed; a test hands in fakes.
@@ -153,28 +206,33 @@ export interface ChatCoreOptions {
     };
     // The accounts a chat may run under; without them every chat runs under its CLI's default account.
     accounts?: AccountLaunches;
+    hooks?: ChatCoreHooks;
 }
 
 /*
  * The chats of one host: a `ChatSession` per chat, its record and its log, and the clients that read
  * them. Everything here holds for any host. What a host adds (notes for the agent, rows of its own,
- * what a clear or a removal takes along) it adds by overriding the protected methods below, which
- * do nothing of their own.
+ * what a clear or a removal takes along) it adds through `ChatCoreOptions.hooks`. A subclass may add
+ * methods of its own over the public ones; the state behind them stays here.
  */
 export class ChatCore {
-    protected readonly providers: ProviderRegistry;
-    protected readonly store: ChatStore | null;
+    // The stores the host handed in, which a subclass reads to copy a chat's bookmarks or visuals.
     protected readonly bookmarks: BookmarkStore | null;
     protected readonly visuals: VisualStore | null;
-    protected readonly accounts: AccountLaunches | null;
-    protected readonly attachments: AttachmentStore;
-    protected readonly env: Record<string, string>;
-    protected readonly chats = new Map<string, ChatSession>();
-    protected readonly creating = new Map<string, Promise<ChatInfo>>();
-    protected readonly sinks = new ClientSinks<AgentEvent>((clientId) => this.composerPreferences.forget(clientId));
-    protected readonly attached = new Map<string, Set<string>>();
-    protected readonly coalescers = new Map<string, DeltaCoalescer>();
-    protected readonly subagents: SubagentReader;
+    private readonly providers: ProviderRegistry;
+    private readonly store: ChatStore | null;
+    private readonly accounts: AccountLaunches | null;
+    private readonly attachments: AttachmentStore;
+    private readonly env: Record<string, string>;
+    private readonly hooks: ChatCoreHooks;
+    private readonly chats = new Map<string, ChatSession>();
+    private readonly creating = new Map<string, Promise<ChatInfo>>();
+    private readonly sinks = new ClientSinks<AgentEvent>((clientId) => this.composerPreferences.forget(clientId));
+    private readonly attached = new Map<string, Set<string>>();
+    // How often a chat's bookmarks or visuals changed, so an attach can tell that its read went stale before it joined.
+    private readonly listChanges = new Map<string, number>();
+    private readonly coalescers = new Map<string, DeltaCoalescer>();
+    private readonly subagents: SubagentReader;
     /* Where Claude Code keeps the projects of its default account on this machine; empty when it has none. */
     readonly claudeProjectsDir: string;
     readonly composerPreferences = new ComposerPreferences();
@@ -222,6 +280,7 @@ export class ChatCore {
         this.nameChat = options.nameChat ?? null;
         this.onInterruptedRun = options.onInterruptedRun ?? null;
         this.limitResume = options.limitResume ?? null;
+        this.hooks = options.hooks ?? {};
         this.commands = {
             ...(options.command ? { claude: options.command } : {}),
             ...(options.codexCommand ? { codex: options.codexCommand } : {})
@@ -231,11 +290,13 @@ export class ChatCore {
         this.env = definedEnv(options.env ?? process.env);
         // Only whoever reads the thread has anything to point a bookmark at or to place a visual in, so the lists go where the thread goes.
         this.bookmarks?.listen((chatId, bookmarks) => {
+            this.listChanged(chatId);
             for (const clientId of this.attached.get(chatId) ?? []) {
                 this.sinks.to(clientId, { event: 'chat.bookmarks', payload: { chatId, bookmarks } });
             }
         });
         this.visuals?.listen((chatId, visuals) => {
+            this.listChanged(chatId);
             for (const clientId of this.attached.get(chatId) ?? []) {
                 this.sinks.to(clientId, { event: 'chat.visuals', payload: { chatId, visuals } });
             }
@@ -340,6 +401,11 @@ export class ChatCore {
         return this.sinks.subscribe(clientId, sink);
     }
 
+    /* Sends one client an event of the host's own, such as a change to something it follows that no chat event carries. */
+    sendTo(clientId: string, event: AgentEvent): void {
+        this.sinks.to(clientId, event);
+    }
+
     /* Registers a chat; nothing is spawned until the first message. An existing chat answers its current info. */
     create(payload: ChatCreatePayload): Promise<ChatInfo> {
         // A create in flight has the chat in the map before its first prompt is sent, so a second caller waits for all of it.
@@ -365,19 +431,20 @@ export class ChatCore {
         const kind = stored?.info.provider ?? payload.provider ?? 'claude';
         const provider = this.providers.get(kind);
         const catalog = provider.catalog;
-        const selection = catalog.normalize(stored?.info.selection ?? this.openingSelection(payload.chatId, kind) ?? payload.selection);
+        const selection = catalog.normalize(stored?.info.selection ?? this.hooks.openingSelection?.(payload.chatId, kind) ?? payload.selection);
         const cwd = stored?.info.cwd ?? payload.cwd ?? this.env.HOME ?? homedir();
-        await this.admit(payload.chatId, cwd);
+        await this.hooks.admit?.(payload.chatId, cwd);
         // A thread on disk keeps its account too. One it lost still opens, and says why on its next turn.
         // A new one without an account takes the person's pick for this CLI, which is refused rather than replaced when it went.
         const account = stored ? stored.info.account : storedAccount(kind, payload.account ?? this.composerPreferences.for(kind).account);
         if (!stored) {
             this.requireAccount(kind, account);
         }
+        const narrowed = (mode: RuntimeMode): RuntimeMode => (this.hooks.runtimeModeFor ? this.hooks.runtimeModeFor(payload.chatId, mode) : mode);
         // Asked again for a chat on disk, since the host may have listed it since.
-        const hidden = this.hiddenFor(payload.chatId) ? { hidden: true } : {};
+        const hidden = this.hooks.hiddenFor?.(payload.chatId) ? { hidden: true } : {};
         const info: ChatInfo = stored?.info
-            ? { ...withoutHidden(stored.info), runtimeMode: this.runtimeModeFor(payload.chatId, stored.info.runtimeMode), ...hidden }
+            ? { ...withoutHidden(stored.info), runtimeMode: narrowed(stored.info.runtimeMode), ...hidden }
             : {
                   ...hidden,
                   chatId: payload.chatId,
@@ -387,7 +454,7 @@ export class ChatCore {
                   agentSessionId: payload.resume ?? null,
                   model: null,
                   selection,
-                  runtimeMode: this.runtimeModeFor(payload.chatId, payload.runtimeMode ?? 'full-access'),
+                  runtimeMode: narrowed(payload.runtimeMode ?? 'full-access'),
                   status: 'idle',
                   running: false,
                   activeTurnId: null,
@@ -398,10 +465,10 @@ export class ChatCore {
         const resume: ResumeDecision = stored ? await this.owedResume(payload.chatId, stored) : { resumeTurnId: null, reason: null };
         const claudeTitles = this.claudeTitles;
         const nameChat = this.nameChat;
-        const base = this.envFor(payload.chatId, this.env);
+        const base = this.hooks.envFor ? this.hooks.envFor(payload.chatId, this.env) : this.env;
         this.logs.set(payload.chatId, await this.openLog(payload.chatId, stored ?? null));
-        const promptNotes = this.promptNotesFor(payload.chatId);
-        const references = this.referencesFor(payload.chatId);
+        const promptNotes = this.hooks.promptNotesFor?.(payload.chatId);
+        const references = this.hooks.referencesFor?.(payload.chatId);
         const session = new ChatSession({
             info,
             ...(this.uiFenceLanguage ? { uiFenceLanguage: this.uiFenceLanguage } : {}),
@@ -418,9 +485,9 @@ export class ChatCore {
                 return env;
             },
             saveGeneratedImage: (ref, upload) => this.attachments.saveGenerated(payload.chatId, ref, upload),
-            instructions: () => this.instructionsFor(payload.chatId),
-            resumeNote: () => this.resumeNoteFor(payload.chatId),
-            folders: () => this.foldersFor(payload.chatId),
+            instructions: () => (this.hooks.instructionsFor ? this.hooks.instructionsFor(payload.chatId) : this.instructions),
+            resumeNote: () => this.hooks.resumeNoteFor?.(payload.chatId) ?? null,
+            folders: () => this.hooks.foldersFor?.(payload.chatId) ?? [],
             ...(promptNotes ? { promptNotes } : {}),
             ...(references ? { references } : {}),
             ...(this.checkpoints ? { checkpoints: this.checkpoints } : {}),
@@ -430,7 +497,7 @@ export class ChatCore {
             save: () => this.persistNow(payload.chatId),
             persistSoon: () => this.persistSoon(payload.chatId),
             ...(kind === 'claude' && claudeTitles
-                ? { readTitle: (agentSessionId: string) => claudeTitles.forSession(agentSessionId, this.claudeProjectsDirOf(session.info)) }
+                ? { readTitle: (agentSessionId: string) => claudeTitles.forSession(agentSessionId, this.claudeProjectsDirOf(session.info), session.info.cwd) }
                 : {}),
             ...(kind === 'codex' && nameChat ? { nameThread: (input: ChatTitleInput) => nameChat(kind, input) } : {}),
             ...(kind === 'claude' ? { subagentSettlement: (toolUseId: string) => this.subagents.claudeSettlement(payload.chatId, toolUseId) } : {}),
@@ -442,11 +509,11 @@ export class ChatCore {
             session.settleOwedResume();
             await session.settleOrphanedSubagents();
         }
-        await this.opened(session, stored ?? null);
+        await this.hooks.opened?.(session, stored ?? null);
         return session.info;
     }
 
-    async storedBackground(chatId: string): Promise<{ turnId: string | null; items: BackgroundWork[]; commands: string[] }> {
+    async storedBackground(chatId: string): Promise<{ turnId: string | null; items: BackgroundWork[]; commands: string[]; goal: boolean }> {
         const record = await this.store?.read(chatId);
         const items = record?.items ?? [];
         const background = items.filter(
@@ -454,7 +521,12 @@ export class ChatCore {
                 isBackgroundWork(item) && (runsInBackground(item) || items.some((note) => note.id === `lost-background-${item.id}`))
         );
         const last = items.findLast((item) => item.kind === 'turn');
-        return { turnId: background.at(-1)?.turnId ?? last?.id ?? null, items: background, commands: (record?.info.background ?? []).map(commandLabel) };
+        return {
+            turnId: background.at(-1)?.turnId ?? last?.id ?? null,
+            items: background,
+            commands: (record?.info.background ?? []).map(commandLabel),
+            goal: record?.info.goal?.status === 'active'
+        };
     }
 
     save(chatId: string): Promise<void> {
@@ -526,9 +598,10 @@ export class ChatCore {
     }
 
     /*
-     * `attach` with the chat's bookmarks and visuals. They are read before the client joins, so a
-     * change written after the read reaches it as `chat.bookmarks` or `chat.visuals` and never falls
-     * between the two. A file that cannot be read leaves its list out rather than the thread.
+     * `attach` with the chat's bookmarks and visuals. They are read before the client joins, and
+     * read again when either changed during the read, so a change reaches the client in the answer
+     * or as `chat.bookmarks` or `chat.visuals` and never falls between the two. A file that cannot be
+     * read leaves its list out rather than the thread.
      */
     async attachWithBookmarks(chatId: string, clientId: string, historyLimit?: number, since?: number): Promise<ChatAttachResult> {
         this.require(chatId);
@@ -536,14 +609,24 @@ export class ChatCore {
             console.error(`The ${what} of chat ${chatId} could not be read:`, errorText(e));
             return undefined;
         };
-        const [bookmarks, visuals] = await Promise.all([
-            this.bookmarks?.read(chatId).catch(unreadable('bookmarks')),
-            this.visuals?.list(chatId).catch(unreadable('visuals'))
-        ]);
+        let bookmarks: ChatBookmark[] | undefined;
+        let visuals: ChatVisual[] | undefined;
+        let changes: number | undefined;
+        do {
+            changes = this.listChanges.get(chatId);
+            [bookmarks, visuals] = await Promise.all([
+                this.bookmarks?.read(chatId).catch(unreadable('bookmarks')),
+                this.visuals?.list(chatId).catch(unreadable('visuals'))
+            ]);
+        } while (this.listChanges.get(chatId) !== changes);
         const result = this.attach(chatId, clientId, historyLimit, since);
         return { ...result, ...(bookmarks === undefined ? {} : { bookmarks }), ...(visuals === undefined ? {} : { visuals }) };
     }
 
+    private listChanged(chatId: string): void {
+        this.listChanges.set(chatId, (this.listChanges.get(chatId) ?? 0) + 1);
+    }
+
     /* Marks a message of the chat's own thread; a message that already has one keeps it. */
     addBookmark(chatId: string, itemId: string, name?: string): Promise<ChatBookmark[]> {
         const item = this.require(chatId).thread.get(itemId);
@@ -601,7 +684,8 @@ export class ChatCore {
         return this.visuals;
     }
 
-    history(chatId: string, cursor: string, limit?: number): ChatHistoryResult {
+    /* The page of a chat's thread before `cursor`, or its newest page without one. */
+    history(chatId: string, cursor?: string, limit?: number): ChatHistoryResult {
         const session = this.require(chatId);
         this.coalescers.get(chatId)?.flush();
         return session.thread.history(limit, cursor);
@@ -654,7 +738,7 @@ export class ChatCore {
         if (row.status !== 'running') {
             return;
         }
-        if (row.origin === 'ruimte') {
+        if (row.origin === HOST_TASK_ORIGIN) {
             throw new ChatError('chat-unsupported', 'This row stands for work the host runs; stop it there');
         }
         session.stopSubagent(toolUseId);
@@ -666,6 +750,11 @@ export class ChatCore {
         this.require(chatId).stopTask(taskId);
     }
 
+    async goal(chatId: string, action: ChatGoalAction): Promise<void> {
+        await this.loaded(chatId);
+        await this.require(chatId).goal(action);
+    }
+
     /* The whole conversation of a subagent of the CLI's own, for an agent that reads it as text. */
     async subagentItems(chatId: string, toolUseId: string): Promise<ChatItem[]> {
         return this.subagents.readAll(chatId, toolUseId);
@@ -676,6 +765,59 @@ export class ChatCore {
         return this.chats.has(chatId) || (await this.store?.has(chatId)) === true;
     }
 
+    /*
+     * Writes the whole record of a chat nobody has loaded, such as a fork's thread before anyone opens it.
+     * The files its messages and generated images point at are copied into its own folder, so removing
+     * the chat they came from leaves them.
+     */
+    async writeRecord(chatId: string, info: ChatInfo, items: ChatItem[], preambles: string[] = []): Promise<void> {
+        if (!this.store) {
+            throw new ChatError('chat-unsupported', 'This host keeps no chat records');
+        }
+        if (this.chats.has(chatId) || this.creating.has(chatId)) {
+            throw new ChatError('chat-busy', `Chat ${chatId} is already loaded`);
+        }
+        const copies = new Map<string, Promise<ChatAttachment>>();
+        const copy = (attachment: ChatAttachment): Promise<ChatAttachment> => {
+            let pending = copies.get(attachment.id);
+            if (!pending) {
+                pending = this.attachments.copy(chatId, attachment);
+                copies.set(attachment.id, pending);
+            }
+            return pending;
+        };
+        const copied = await Promise.all(
+            items.map(async (item): Promise<ChatItem> => {
+                if (item.kind === 'user' && item.attachments?.length) {
+                    return { ...item, attachments: await Promise.all(item.attachments.map(copy)) };
+                }
+                const generated = generatedImageAttachment(item);
+                if (item.kind === 'tool' && generated) {
+                    return { ...item, input: { ...(item.input as Record<string, unknown>), attachment: await copy(generated) } };
+                }
+                return item;
+            })
+        );
+        await this.store.write(chatId, info, copied, { seq: 0, resetSeq: 0 }, preambles);
+    }
+
+    /*
+     * Removes what a chat nobody loaded keeps on disk: its record and log, attachments, bookmarks and
+     * visuals. False, with nothing removed, for a chat that is loaded or loading; `kill` removes that one.
+     */
+    async deleteRecord(chatId: string): Promise<boolean> {
+        if (this.chats.has(chatId) || this.creating.has(chatId)) {
+            return false;
+        }
+        await Promise.all([
+            this.store?.delete(chatId),
+            this.attachments.removeAll(chatId),
+            this.bookmarks?.removeChat(chatId),
+            this.visuals?.removeChat(chatId)
+        ]);
+        return true;
+    }
+
     /* The turn a chat took last, read off the record without loading a chat nobody has; null before its first. */
     async lastTurn(chatId: string): Promise<ChatTurnItem | null> {
         const session = this.chats.get(chatId);
@@ -797,6 +939,14 @@ export class ChatCore {
         return session.skills(() => this.skillIndex.list(session.info.provider, session.info.cwd));
     }
 
+    /* Ends the chat's CLI and keeps its conversation; the next message resumes it in a process that reads its skills and plugins again. */
+    async restart(chatId: string): Promise<void> {
+        const session = this.require(chatId);
+        const ended = session.restart();
+        this.skillIndex.forget(session.info.provider, session.info.cwd);
+        await ended;
+    }
+
     compact(chatId: string): void {
         const session = this.require(chatId);
         if (session.busy) {
@@ -811,10 +961,10 @@ export class ChatCore {
         if (session.busy && !force) {
             throw new ChatError('chat-busy', `Chat ${chatId} is still working on the previous message`);
         }
-        await this.clearing(chatId);
+        await this.hooks.clearing?.(chatId);
         const ended = session.clear(force);
         // Before the record is written, so what it takes along from the record is gone from the write as well.
-        const cleared = this.cleared(chatId);
+        const cleared = this.hooks.cleared?.(chatId);
         // A debounced write still waiting holds the old thread and must not land after the empty one.
         this.cancelWaiting(chatId);
         // Folded right away: every line before the reset describes a thread that is gone.
@@ -859,6 +1009,17 @@ export class ChatCore {
         }
     }
 
+    /* Holds a chat at `needs-you` for what the host asks a person; false for a chat that is not here. */
+    holdForPerson(chatId: string, key: string): boolean {
+        const session = this.chats.get(chatId);
+        session?.holdForPerson(key);
+        return session !== undefined;
+    }
+
+    releaseHold(chatId: string, key: string): void {
+        this.chats.get(chatId)?.releaseHold(key);
+    }
+
     /* Removes a chat: its CLI, its record, its log, its attachments, its bookmarks and its visuals. */
     async kill(chatId: string): Promise<void> {
         await this.loaded(chatId);
@@ -879,9 +1040,10 @@ export class ChatCore {
         this.activity.delete(chatId);
         this.chats.delete(chatId);
         this.attached.delete(chatId);
+        this.listChanges.delete(chatId);
         this.announced.delete(chatId);
         const snapshot = session.thread.snapshot();
-        this.forgotten(chatId);
+        this.hooks.forgotten?.(chatId);
         await writing;
         await ended;
         await Promise.all([
@@ -889,7 +1051,7 @@ export class ChatCore {
             this.attachments.removeAll(chatId),
             this.bookmarks?.removeChat(chatId),
             this.visuals?.removeChat(chatId),
-            this.removed(chatId, snapshot)
+            this.hooks.removed?.(chatId, snapshot)
         ]);
     }
 
@@ -935,7 +1097,7 @@ export class ChatCore {
             }
             await this.create({ chatId });
         }
-        await this.chats.get(chatId)?.resume(turnId, attempt, await this.resumeWords(chatId));
+        await this.chats.get(chatId)?.resume(turnId, attempt, (await this.hooks.resumeWords?.(chatId)) ?? DEFAULT_RESUME_WORDS);
     }
 
     /*
@@ -955,7 +1117,7 @@ export class ChatCore {
             return;
         }
         const turn = session.thread.get(turnId);
-        const ended = this.endedAt(chatId);
+        const ended = this.hooks.endedAt?.(chatId) ?? null;
         if (turn !== undefined && ended !== null && ended >= turn.createdAt) {
             session.lapseResume();
             return;
@@ -988,6 +1150,10 @@ export class ChatCore {
             if (this.chats.has(chatId) || this.creating.has(chatId)) {
                 continue;
             }
+            // Parsing the whole thread of every settled chat was most of the cost of a start.
+            if (await this.store.settled(chatId).catch(() => false)) {
+                continue;
+            }
             const record = await this.store.read(chatId).catch(() => null);
             const unowed = record?.info.resumeAt !== undefined && this.limitResume?.owed(chatId) === false;
             if (record !== null && (interruptedTurn(record) !== null || unowed)) {
@@ -1040,7 +1206,7 @@ export class ChatCore {
                     items,
                     { seq: log?.seq ?? 0, resetSeq: log?.resetSeq ?? 0 },
                     session.preambles,
-                    this.recordExtras(chatId),
+                    this.hooks.recordExtras?.(chatId) ?? {},
                     session.uiAccessRecord
                 );
             } catch (e) {
@@ -1059,11 +1225,6 @@ export class ChatCore {
         await this.creating.get(chatId)?.catch(() => undefined);
     }
 
-    protected persist(chatId: string): void {
-        this.cancelWaiting(chatId);
-        void this.persistNow(chatId).catch((e) => console.error(`Chat record for ${chatId} failed:`, errorText(e)));
-    }
-
     protected require(chatId: string): ChatSession {
         const session = this.chats.get(chatId);
         if (!session) {
@@ -1072,93 +1233,9 @@ export class ChatCore {
         return session;
     }
 
-    /* What the agent is told once at the start of every process of this chat; null for nothing. */
-    protected instructionsFor(_chatId: string): string | null {
-        return this.instructions;
-    }
-
-    /* What of the instructions a resumed thread hears again in front of its next prompt, for a CLI that ignores them on a resume. */
-    protected resumeNoteFor(_chatId: string): string | null {
-        return null;
-    }
-
-    /*
-     * Folders outside its working directory a chat's agent may reach without asking, absolute. Asked
-     * before every turn, so a host can hand one over for as long as it is needed: a change starts the
-     * next turn in a new process that resumes the thread, and never cuts a turn in flight.
-     */
-    protected foldersFor(_chatId: string): readonly string[] {
-        return [];
-    }
-
-    /* Whether no list of chats shows this one, which `ChatInfo.hidden` says to every client. */
-    protected hiddenFor(_chatId: string): boolean {
-        return false;
-    }
-
-    /* What the host says in front of a chat's next real prompt, beside what the chat keeps itself. */
-    protected promptNotesFor(_chatId: string): PromptNotes | undefined {
-        return undefined;
-    }
-
-    /* How the chats a person attached to a message are named to the agent; without it they are dropped. */
-    protected referencesFor(_chatId: string): ChatReferences | undefined {
-        return undefined;
-    }
-
-    /* The environment of this chat's CLI before its account adds its own. */
-    protected envFor(_chatId: string, base: Record<string, string>): Record<string, string | undefined> {
-        return base;
-    }
-
-    /* Throws for a folder this chat may not start in; asked every time a chat is loaded. */
-    protected async admit(_chatId: string, _cwd: string): Promise<void> {}
-
-    /* The model a new chat starts on when the host already knows; the explicit one still wins. */
-    protected openingSelection(_chatId: string, _kind: AgentKind): ModelSelection | undefined {
-        return undefined;
-    }
-
-    /* The mode a chat runs in, which a host may narrow whatever its record or its client says. */
-    protected runtimeModeFor(_chatId: string, mode: RuntimeMode): RuntimeMode {
-        return mode;
-    }
-
-    /* A chat just loaded or made, its stored turns settled; whatever the host lays down in it goes here. */
-    protected async opened(_session: ChatSession, _stored: ChatRecord | null): Promise<void> {}
-
-    /* What the host keeps in the chat's record beside the thread. */
-    protected recordExtras(_chatId: string): ChatRecordExtras {
-        return {};
-    }
-
-    /* The chat was cleared; what runs before the first await is in the record written right after. */
-    protected async cleared(_chatId: string): Promise<void> {}
-
-    protected async clearing(_chatId: string): Promise<void> {}
-
-    /* The chat left memory for good, before its files go. */
-    protected forgotten(_chatId: string): void {}
-
-    /* The chat was removed; what the host keeps of it goes along. */
-    protected async removed(_chatId: string, _chat: { info: ChatInfo; items: ChatItem[] }): Promise<void> {}
-
-    /* An event of a chat went out, after the observers and before the clients reading its thread. */
-    protected broadcasted(_chatId: string, _event: ChatEvent): void {}
-
-    /* When whoever opened this chat stopped it; a turn from before that is never taken up again. */
-    protected endedAt(_chatId: string): number | null {
-        return null;
-    }
-
-    /* Why a turn the host went down in stays down when `onInterruptedRun` says no, in the words of the note it ends with. */
-    protected unownedReason(_chatId: string): string {
-        return 'nothing holds this chat any more';
-    }
-
-    /* How a turn the host went down in is taken up in this chat. */
-    protected async resumeWords(_chatId: string): Promise<ResumeWords> {
-        return DEFAULT_RESUME_WORDS;
+    private persist(chatId: string): void {
+        this.cancelWaiting(chatId);
+        void this.persistNow(chatId).catch((e) => console.error(`Chat record for ${chatId} failed:`, errorText(e)));
     }
 
     /* A write that may wait: a long thread is not rewritten for every small change. */
@@ -1200,7 +1277,7 @@ export class ChatCore {
             }
             // A delta held back is already in the thread, so it gets its seq before the snapshot says where it ends.
             this.coalescers.get(chatId)?.flush();
-            const extras = this.recordExtras(chatId);
+            const extras = this.hooks.recordExtras?.(chatId) ?? {};
             const uiAccess = session.uiAccessRecord;
             const unlogged = JSON.stringify([session.preambles, extras, uiAccess]);
             const folds = fold || log.size > COMPACT_ABOVE_BYTES || !log.onDisk;
@@ -1250,7 +1327,7 @@ export class ChatCore {
         for (const sink of this.observers) {
             sink({ event: 'chat.event', payload });
         }
-        this.broadcasted(chatId, event);
+        this.hooks.broadcasted?.(chatId, event);
         for (const clientId of this.attached.get(chatId) ?? []) {
             this.sinks.to(clientId, { event: 'chat.event', payload });
         }
@@ -1273,14 +1350,15 @@ export class ChatCore {
      */
     private announceStatus(chatId: string, info: ChatInfo): void {
         // A limit, the resume owed after it and subagents still at work are what a header shows of an idle chat, so they count as a change too,
-        // and so does a request opening or settling while the chat already waits on another.
+        // and so does a request opening or settling while the chat already waits on another, and a goal set, moving on or gone.
         const said = JSON.stringify([
             info.status,
             info.limit ?? null,
             info.resumeAt ?? null,
             info.resumeAtReset ?? null,
             info.delegating ?? false,
-            info.requests?.map((request) => request.requestId) ?? []
+            info.requests?.map((request) => request.requestId) ?? [],
+            info.goal === undefined ? null : [info.goal.status, info.goal.objective]
         ]);
         if (this.announced.get(chatId) === said) {
             return;
@@ -1322,7 +1400,7 @@ export class ChatCore {
         if (stored.info.agentSessionId === null) {
             return skip('the agent had not started a session to resume yet');
         }
-        const ended = this.endedAt(chatId);
+        const ended = this.hooks.endedAt?.(chatId) ?? null;
         if (ended !== null && ended >= turn.createdAt) {
             return skip('the agent that opened it was stopped');
         }
@@ -1331,7 +1409,7 @@ export class ChatCore {
         }
         try {
             const owed = await this.onInterruptedRun({ chatId, turnId: turn.id, attempt: (turn.attempt ?? 1) + (turn.resumePending ? 0 : 1) });
-            return owed ? { resumeTurnId: turn.id, reason: null } : skip(this.unownedReason(chatId));
+            return owed ? { resumeTurnId: turn.id, reason: null } : skip(this.hooks.unownedReason?.(chatId) ?? 'nothing holds this chat any more');
         } catch (e) {
             console.error(`Owing a resume for chat ${chatId} failed:`, errorText(e));
             return skip(errorText(e));