@oharness/engine 0.9.2 → 0.10.0

package/dist/agent/agent.js

@@ -1,17 +1,24 @@
+import { GOAL_MAX_TURNS, GOAL_TOOL, MAX_GOAL_NUDGES, activeGoal, goalNudge, goalPromptSection, goalTool } from "./goal.js";
+import { COMPUTER_KEY, computerOn, computerPromptSection, isComputerTool } from "../computer/mode.js";
 import { randomUUID } from "node:crypto";
 import { errorMessage } from "../core/errors.js";
-import { estimateStringTokens } from "../core/tokens.js";
+import { estimateMessagesTokens, estimateStringTokens, estimateToolsTokens } from "../core/tokens.js";
 import { assistantMessage, emptyUsage, messageText, userMessage } from "../core/types.js";
 import { thinkingFor } from "../providers/types.js";
+import { WORKTREE_START_TOOL, worktreeStartTool } from "../tools/builtin/worktree.js";
+import { BASH_CWD_KEY } from "../tools/builtin/bash.js";
+import { createWorktree, finishWorktree, worktreeStatus } from "../worktree/index.js";
 import { createTaskTool } from "../tools/builtin/task.js";
+import { TASK_MESSAGE_TOOL, TASK_OUTPUT_TOOL, TASK_STOP_TOOL, taskMessageTool, taskOutputTool, taskStopTool, } from "../tools/builtin/task-control.js";
+import { BackgroundTasks, formatNotification } from "./background.js";
 import { ARCHIVE_READER } from "../tools/builtin/recall.js";
 import { ARTIFACT_METADATA_KEY } from "../tools/builtin/artifact.js";
 import { previewJson } from "../util/json.js";
 import { AsyncQueue, mergeStreams } from "../util/queue.js";
 import { createLogger } from "../util/logger.js";
-import { compact, shouldCompact } from "./compaction.js";
+import { compact, compactionPoint, shouldCompact } from "./compaction.js";
 import { capToolResult } from "./overflow.js";
-import { checkWrite, resolveWithin } from "./workspace.js";
+import { checkWrite, resolveWithin, retargetPolicy } from "./workspace.js";
 import { SkillRegistry } from "./skills.js";
 import { MemoryStore, recallFromStores } from "./memory.js";
 import { DEFAULT_MEMORY_POLICY } from "./memory-limits.js";
@@ -23,7 +30,18 @@ import { HookRegistry } from "./hooks.js";
 import { buildSystemPrompt } from "./prompt.js";
 import { ASK_USER_TOOL } from "../tools/questions.js";
 import { SubagentRegistry } from "./subagent.js";
+function withoutSignal(opts) {
+    const { signal: _signal, ...rest } = opts;
+    return rest;
+}
 const DEFAULT_MAX_TURNS = 60;
+/**
+ * How long an idle agent lets background results gather before asking for a
+ * turn to read them, so tasks ending together are answered together.
+ */
+const TASK_WAKE_DELAY_MS = 500;
+/** How long task changes gather before they are written down. */
+const TASK_SAVE_DELAY_MS = 1000;
 /** Session state key: ids of notes attached since the last compaction. */
 const RECALLED = "memory:recalled";
 /** Session state key: how much of the transcript an end-of-run extraction has covered. */
@@ -57,14 +75,6 @@ function recalledIds(state, messages) {
     }
     return ids;
 }
-/**
- * The agentic loop: prompt the model, run whatever tools it asks for, feed the
- * results back, repeat until it stops calling tools.
- *
- * Everything provider-specific lives behind `Provider`, so this loop is the
- * same regardless of which model is selected — including when the model
- * changes partway through a session.
- */
 export class Agent {
     session;
     tools;
@@ -95,6 +105,18 @@ export class Agent {
     pluginSections = [];
     /** Recall over `memory` for agents embedded without a plugin host. */
     legacyMemory;
+    /** Subagents running in the background; made on first use. */
+    background;
+    wakeTimer;
+    /** Frontends watching background tasks, kept until the tasks exist. */
+    changeListeners = new Set();
+    /** What each background task was asked, and its subagent once it has one. */
+    taskStates = new Map();
+    restoring;
+    saveTimer;
+    /** Closed or deleted: nothing more is saved, and nothing more starts. */
+    tasksClosed = false;
+    saveChain = Promise.resolve();
     constructor(opts) {
         this.opts = opts;
         this.session = opts.session;
@@ -128,11 +150,25 @@ export class Agent {
         if (!this.tools.has("skill") && this.skills.size > 0) {
             this.tools.register(createSkillTool(this.skills));
         }
+        if (!this.tools.has(GOAL_TOOL))
+            this.tools.register(goalTool);
+        // Shown only where a frontend can host the session it starts; see visibleTools.
+        if (!this.tools.has(WORKTREE_START_TOOL))
+            this.tools.register(worktreeStartTool);
         // The task tool has to be built here: its description enumerates the
         // subagent types that actually exist in this configuration.
         if (!this.tools.has("task") && this.subagents.list().length > 0) {
             this.tools.register(createTaskTool(this));
         }
+        // Shown only where background tasks can be offered; see visibleTools.
+        if (this.tools.has("task")) {
+            if (!this.tools.has(TASK_OUTPUT_TOOL))
+                this.tools.register(taskOutputTool);
+            if (!this.tools.has(TASK_STOP_TOOL))
+                this.tools.register(taskStopTool);
+            if (!this.tools.has(TASK_MESSAGE_TOOL))
+                this.tools.register(taskMessageTool);
+        }
     }
     /**
      * Announce a model switch so a UI can render it and hooks can react.
@@ -238,35 +274,387 @@ export class Agent {
     resolvePath(input, access) {
         return resolveWithin(this.opts.workspace, this.session.cwd, input, access);
     }
+    async startWorktree(opts) {
+        const launch = this.opts.worktreeLauncher?.();
+        if (!launch)
+            throw new Error("this frontend cannot start a session in a worktree");
+        return launch({ ...opts, from: { cwd: this.session.cwd, sessionId: this.session.id } });
+    }
     listSubagentTypes() {
         return this.subagents.summaries();
     }
     async runSubagent(opts) {
+        const child = await this.prepareSubagent(opts);
+        try {
+            const result = await this.runChild(child, opts.prompt, opts.signal);
+            // Propagate state the subagent built up (e.g. files it read). Not from a
+            // worktree: what it read there are paths in another tree.
+            if (!child.worktree)
+                for (const [key, value] of child.agent.session.state)
+                    this.session.state.set(key, value);
+            // A worktree it left changes in is named in the result: the parent has
+            // to decide what happens to that work.
+            const kept = await this.worktreeNote(child);
+            const text = kept
+                ? `${result.text}\n\n[worktree] ${kept} It is kept: review it, then merge, push or apply it, or discard it from the sidebar.`
+                : result.text;
+            return { text, turns: result.turns, usage: result.usage };
+        }
+        finally {
+            await this.disposeChild(child);
+        }
+    }
+    // --- Background tasks ----------------------------------------------------
+    /**
+     * Subagents running behind this conversation, offered only while someone
+     * can start a turn to read their results in. Once any exist they stay
+     * reachable, so they can still be listed, messaged and stopped.
+     */
+    get backgroundTasks() {
+        if (!this.backgroundAvailable())
+            return undefined;
+        // Read without making the table: every open conversation is asked for
+        // its list, and most never start a task.
+        return {
+            start: (opts) => {
+                const state = { opts: withoutSignal(opts) };
+                const view = this.tasks().start(this.backgroundSpec(state));
+                this.taskStates.set(view.id, state);
+                return view;
+            },
+            get: (id) => this.background?.get(id),
+            list: () => this.background?.list() ?? [],
+            stop: (id) => this.background?.stop(id) ?? false,
+            send: (id, message) => this.background?.send(id, message) ?? "unknown",
+            dismiss: (id) => this.background?.dismiss(id) ?? false,
+        };
+    }
+    /** A task's conversation so far, for a frontend to show. */
+    backgroundTranscript(id) {
+        return this.background?.transcript(id);
+    }
+    /** Every change to a background task, for a frontend to redraw from. */
+    onBackgroundChange(listener) {
+        this.changeListeners.add(listener);
+        const off = this.background?.onChange(listener);
+        return () => {
+            this.changeListeners.delete(listener);
+            off?.();
+        };
+    }
+    /**
+     * The conversation is being closed, not ended: write its tasks down as they
+     * stand, then stop them. Opened again, the ones that were running come back
+     * interrupted and can be followed up — as after a restart.
+     */
+    async closeBackgroundTasks() {
+        if (this.tasksClosed)
+            return;
+        if (this.saveTimer)
+            clearTimeout(this.saveTimer);
+        this.saveTimer = undefined;
+        await this.saveTasks();
+        this.endBackgroundTasks();
+    }
+    /**
+     * The conversation is being deleted: stop its tasks and write nothing more.
+     * Resolves once a write already under way has landed, so deleting the
+     * store afterwards cannot be undone by it.
+     */
+    async discardBackgroundTasks() {
+        this.endBackgroundTasks();
+        await this.saveChain;
+    }
+    endBackgroundTasks() {
+        this.tasksClosed = true;
+        if (this.wakeTimer)
+            clearTimeout(this.wakeTimer);
+        if (this.saveTimer)
+            clearTimeout(this.saveTimer);
+        this.wakeTimer = undefined;
+        this.saveTimer = undefined;
+        this.background?.stopAll();
+        this.background?.detach();
+    }
+    backgroundAvailable() {
+        return Boolean(this.background) || Boolean(this.opts.taskWaker?.());
+    }
+    tasks() {
+        if (!this.background) {
+            this.background = new BackgroundTasks({
+                ...(this.opts.maxBackgroundTasks ? { maxConcurrent: this.opts.maxBackgroundTasks } : {}),
+                ...(this.opts.lifecycleSignal ? { signal: this.opts.lifecycleSignal } : {}),
+            });
+            // While a run is going its own loop reads results in at the next gap;
+            // only an idle agent needs someone to start a turn for them. And an
+            // ended task is written down at once rather than after the usual pause:
+            // its result is the one thing a restart must not lose.
+            this.background.onSettled(() => {
+                if (!this.running)
+                    this.scheduleWake();
+                void this.saveTasks();
+            });
+            for (const listener of this.changeListeners)
+                this.background.onChange(listener);
+            this.background.onChange(() => this.scheduleSave());
+        }
+        return this.background;
+    }
+    /**
+     * A background task's subagent, made for each run and let go after it.
+     *
+     * Between runs a task holds only its conversation and, if it changed
+     * anything, its worktree: no browser, no claim on the computer, no agent.
+     * A follow-up — or the first one after a restart — builds the subagent
+     * again from those, so both paths are the same path.
+     */
+    backgroundSpec(state) {
+        const once = async (input, signal, report) => {
+            const child = await this.prepareSubagent(state.opts, {
+                messages: state.messages ?? [],
+                ...(state.worktree ? { worktree: state.worktree } : {}),
+                ...(state.equipment ? { equipment: state.equipment } : {}),
+            });
+            // Its tree is gone — removed by hand, or after a restart — and it now
+            // works in a new one: said up front, since its conversation names the
+            // old paths.
+            const moved = state.worktree && child.worktree && state.worktree.path !== child.worktree.path
+                ? `[Note: your earlier worktree at ${state.worktree.path} no longer exists. You are now working in ${child.worktree.path}; files you changed there are not here.]\n\n`
+                : "";
+            state.child = child;
+            state.equipment = child.equipment;
+            if (child.worktree)
+                state.worktree = child.worktree;
+            try {
+                const result = await this.runChild(child, moved + input, signal, report);
+                const kept = await this.worktreeNote(child);
+                return { ...result, ...(kept ? { worktree: kept } : {}) };
+            }
+            finally {
+                // The agent goes; its conversation, tree and browser stay with the
+                // task until it is stopped, or its conversation closed.
+                state.messages = [...child.agent.session.messages];
+                state.child = undefined;
+            }
+        };
+        return {
+            agentType: state.opts.agentType,
+            description: state.opts.description || state.opts.agentType,
+            run: (signal, report) => once(state.opts.prompt, signal, report),
+            // A task that failed before its subagent ever ran has no conversation to
+            // continue; the follow-up then goes with the task it was given.
+            resume: (message, signal, report) => once(state.messages?.length ? message : `${state.opts.prompt}\n\n${message}`, signal, report),
+            interject: (message) => Boolean(state.child?.agent.interject(message)),
+            transcript: () => state.child?.agent.session.messages ?? state.messages ?? [],
+            dispose: async () => {
+                await state.equipment?.release().catch(() => { });
+                state.equipment = undefined;
+                if (state.worktree)
+                    await this.dropIfUntouched(state.worktree);
+            },
+        };
+    }
+    /**
+     * Put back the background tasks this conversation had before a restart.
+     *
+     * Called by a frontend when it opens the conversation; safe to call again.
+     * A task that was still running when the app closed comes back as failed
+     * and says why — its subagent's process is gone — but keeps its
+     * conversation, so a follow-up carries on from where it stopped. A result
+     * nobody had been told about is still read in with the next turn.
+     */
+    async restoreBackgroundTasks() {
+        if (this.restoring)
+            return this.restoring;
+        this.restoring = (async () => {
+            if (this.tasksClosed)
+                return 0;
+            const saved = await this.session.loadTasks().catch(() => []);
+            // Closed while it was reading: bringing them back now would make a
+            // table nothing will ever close.
+            if (this.tasksClosed)
+                return 0;
+            let restored = 0;
+            for (const raw of saved) {
+                const item = raw;
+                if (!item?.view?.id || !item.options?.agentType || !this.subagents.get(item.options.agentType))
+                    continue;
+                const view = { ...item.view };
+                let delivered = item.delivered === true;
+                if (view.status === "running" || view.status === "queued") {
+                    view.status = "failed";
+                    view.error = "Interrupted: OHarness closed while this task was running. Send it a message to carry on from where it stopped.";
+                    view.endedAt = Date.now();
+                    delete view.activity;
+                    delivered = true;
+                }
+                const state = {
+                    opts: item.options,
+                    messages: Array.isArray(item.messages) ? item.messages : [],
+                    ...(item.worktree ? { worktree: item.worktree } : {}),
+                };
+                this.taskStates.set(view.id, state);
+                this.tasks().restore(view, this.backgroundSpec(state), delivered);
+                restored++;
+            }
+            return restored;
+        })();
+        return this.restoring;
+    }
+    /** Write the tasks down a moment after they change, so a burst is one write. */
+    scheduleSave() {
+        if (this.saveTimer || this.tasksClosed)
+            return;
+        this.saveTimer = setTimeout(() => {
+            this.saveTimer = undefined;
+            void this.saveTasks();
+        }, TASK_SAVE_DELAY_MS);
+    }
+    /**
+     * One write at a time, in order. Each takes its snapshot when its turn
+     * comes, so a later state is never overwritten by an earlier one landing
+     * last — a task that ended would come back as running.
+     */
+    saveTasks() {
+        const next = this.saveChain.then(() => this.writeTasks());
+        this.saveChain = next.catch(() => { });
+        return next;
+    }
+    async writeTasks() {
+        // Shutting down stops every task; writing that down would bring them back
+        // as stopped for good, when they were only interrupted. The last save from
+        // while they ran is the truer record. A closed conversation has already
+        // written its own.
+        if (!this.background || this.tasksClosed || this.opts.lifecycleSignal?.aborted)
+            return;
+        const tasks = this.background.saved().flatMap(({ view, delivered }) => {
+            const state = this.taskStates.get(view.id);
+            if (!state)
+                return [];
+            const worktree = state.child?.worktree ?? state.worktree;
+            return [{
+                    view,
+                    delivered,
+                    options: state.opts,
+                    messages: [...(state.child?.agent.session.messages ?? state.messages ?? [])],
+                    ...(worktree ? { worktree } : {}),
+                }];
+        });
+        await this.session.saveTasks(tasks).catch((err) => {
+            this.logger.warn("could not save background tasks", { error: errorMessage(err) });
+        });
+    }
+    scheduleWake() {
+        if (this.wakeTimer || this.tasksClosed)
+            return;
+        this.wakeTimer = setTimeout(() => {
+            this.wakeTimer = undefined;
+            if (this.running || !this.background?.hasUndelivered())
+                return;
+            this.opts.taskWaker?.()?.(this.session.id);
+        }, TASK_WAKE_DELAY_MS);
+    }
+    /**
+     * Read the results of background tasks that have ended into the
+     * conversation, as one message saying what is still running.
+     *
+     * Synthetic, like a goal nudge: nobody typed it, so it skips the prompt hook
+     * and memory recall, and never titles the session.
+     */
+    async *takeNotices() {
+        const ended = this.background?.takeUndelivered() ?? [];
+        if (!ended.length)
+            return false;
+        const text = formatNotification(ended, this.background?.active() ?? []);
+        await this.session.addMessage({
+            role: "user",
+            content: [{ type: "text", text }],
+            // What a transcript needs to draw it as a card rather than as text
+            // somebody typed: which tasks, and how each ended.
+            meta: {
+                timestamp: Date.now(),
+                synthetic: true,
+                taskNotification: ended.map((task) => ({ id: task.id, description: task.description, status: task.status })),
+            },
+        });
+        yield { type: "task_notification", tasks: ended, text };
+        return true;
+    }
+    /** Where this agent's permission cards go, and who they say is asking. */
+    interactionPlace() {
+        return {
+            sessionId: this.opts.interactionSessionId ?? this.session.id,
+            ...(this.opts.interactionLabel ? { from: this.opts.interactionLabel } : {}),
+        };
+    }
+    // --- Subagents -----------------------------------------------------------
+    /** A subagent ready to run: its agent, the tree it works in, what it holds. */
+    async prepareSubagent(opts, seed) {
         const definition = this.subagents.get(opts.agentType);
         if (!definition)
             throw new Error(`unknown agent type: ${opts.agentType}`);
         // A subagent gets its own transcript and a filtered tool set, but shares
         // the parent's scratch state so file-read tracking stays coherent.
         const { Session: SessionClass } = await import("./session.js");
+        // Its own tree when asked for, or when the agent type always wants one:
+        // several editing subagents in one checkout would trip over each other.
+        // Branched from this checkout's HEAD rather than the remote, so it starts
+        // from the commits the parent is looking at.
+        const isolated = opts.isolation === "worktree" || definition.isolation === "worktree";
+        // A restored task goes back to its own tree while that still exists.
+        const kept = seed?.worktree && (await worktreeStatus(seed.worktree).catch(() => undefined))?.exists ? seed.worktree : undefined;
+        const worktree = kept ?? (isolated
+            ? await createWorktree(this.session.cwd, {
+                task: opts.description || definition.name,
+                slug: opts.description ? undefined : `${definition.name}-agent`,
+                base: "HEAD",
+                fetch: false,
+            })
+            : undefined);
+        const childCwd = worktree?.cwd ?? this.session.cwd;
         const child = new SessionClass({
-            cwd: this.session.cwd,
+            cwd: childCwd,
             model: opts.model ?? definition.model ?? this.session.model.id,
             providers: this.session.providers,
             permissionMode: this.session.permissions.getMode(),
             store: false,
+            // Through the constructor rather than added one by one: it drops a
+            // tail a run was cut off in — a tool call with no result — which no
+            // provider accepts a following message after.
+            ...(seed?.messages.length ? { messages: [...seed.messages] } : {}),
         });
         for (const [key, value] of this.session.state)
             child.state.set(key, value);
+        // A shell that had cd'd somewhere in the parent's tree must start in its own.
+        if (worktree)
+            child.state.delete(BASH_CWD_KEY);
+        // Control of the screen is never inherited by default: a subagent works
+        // unattended, and drives the computer only when asked to and only while
+        // the conversation that asked has it switched on.
+        if (!(opts.computer && computerOn(this.session.state)))
+            child.state.delete(COMPUTER_KEY);
         child.permissions.onDecision((entry) => {
             this.audit({ type: "permission", timestamp: Date.now(), sessionId: child.id, entry });
         });
         // A subagent does not ask the person questions. Its events never reach the
         // parent's stream, so a card it raised would have no call to belong to —
         // and needing to ask usually means the delegation was underspecified,
-        // which is the parent's to resolve.
+        // which is the parent's to resolve. Nor does it see the parent's
+        // background tasks: it has none of its own.
         const childTools = definition.tools ? this.tools.filtered(definition.tools) : this.tools.clone();
         childTools.unregister(ASK_USER_TOOL);
-        const childAgent = new Agent({
+        childTools.unregister(TASK_OUTPUT_TOOL);
+        childTools.unregister(TASK_STOP_TOOL);
+        childTools.unregister(TASK_MESSAGE_TOOL);
+        const label = opts.description ? `${definition.name}: ${opts.description}` : definition.name;
+        // Its own browser tabs and its own place in the computer's leases, so two
+        // subagents — or a subagent and its parent — never act on one page.
+        let equipment = seed?.equipment;
+        if (equipment?.bind)
+            equipment.bind(childTools);
+        else
+            equipment = this.opts.equipSubagent?.(child.id, label, childTools);
+        const agent = new Agent({
             ...this.opts,
             questionPrompt: undefined,
             session: child,
@@ -275,40 +663,96 @@ export class Agent {
             appendSystemPrompt: undefined,
             maxTurns: definition.maxTurns ?? this.opts.maxTurns,
             agentId: `${this.agentId}/${definition.name}`,
+            ...(worktree && this.opts.workspace
+                ? { workspace: retargetPolicy(this.opts.workspace, this.session.cwd, worktree.cwd) }
+                : {}),
+            // A subagent hands work back to its parent; it does not start sessions
+            // or background tasks.
+            worktreeLauncher: undefined,
+            taskWaker: undefined,
+            equipSubagent: undefined,
+            ...(equipment?.onRunStart ? { onRunStart: equipment.onRunStart } : {}),
+            interactionSessionId: this.opts.interactionSessionId ?? this.session.id,
+            interactionLabel: label,
             // One level of delegation: a subagent may not spawn further subagents.
             subagents: new SubagentRegistry([]),
             // The parent already attached what matched the user's message, and a
             // subagent's prompt is the parent's wording rather than the user's.
             memoryProvider: undefined,
         });
+        return { agent, definition, ...(worktree ? { worktree } : {}), ...(equipment ? { equipment } : {}) };
+    }
+    /**
+     * One run of a subagent, to its end: its first prompt, or a later message.
+     *
+     * `report` is there only for a background task: it is what lets a look at
+     * the task say what the subagent is doing now.
+     */
+    async runChild(child, input, signal, report) {
         let text = "";
         let turns = 0;
         let usage = emptyUsage();
-        for await (const event of childAgent.run(opts.prompt, { signal: opts.signal })) {
-            if (event.type === "assistant_message") {
-                const messageBody = messageText(event.message);
-                if (messageBody.trim())
-                    text = messageBody;
-            }
-            else if (event.type === "done") {
-                turns = event.turns;
-                usage = event.usage;
+        // Said to it after its last look at its inbox would otherwise sit there
+        // until some later run, out of context: answered now, as one more run.
+        for (let next = input; next !== undefined;) {
+            for await (const event of child.agent.run(next, { ...(signal ? { signal } : {}) })) {
+                if (event.type === "assistant_message") {
+                    const messageBody = messageText(event.message);
+                    if (messageBody.trim())
+                        text = messageBody;
+                }
+                else if (event.type === "turn_start") {
+                    report?.turn();
+                }
+                else if (event.type === "tool_start") {
+                    report?.activity(event.title);
+                }
+                else if (event.type === "done") {
+                    turns += event.turns;
+                    usage = event.usage;
+                }
             }
+            const unread = signal?.aborted ? [] : child.agent.takeUnread();
+            next = unread.length ? unread.map((entry) => entry.text).join("\n\n") : undefined;
         }
-        // Propagate state the subagent built up (e.g. files it read).
-        for (const [key, value] of child.state)
-            this.session.state.set(key, value);
         await this.hooks.run({
             event: "SubagentStop",
             sessionId: this.session.id,
-            agentId: `${this.agentId}/${definition.name}`,
+            agentId: `${this.agentId}/${child.definition.name}`,
             cwd: this.session.cwd,
         });
-        return {
-            text,
-            turns,
-            usage: { inputTokens: usage.inputTokens, outputTokens: usage.outputTokens },
-        };
+        return { text, turns, usage: { inputTokens: usage.inputTokens, outputTokens: usage.outputTokens } };
+    }
+    /** What a subagent left in its worktree, when it left anything. */
+    async worktreeNote(child) {
+        if (!child.worktree)
+            return undefined;
+        const status = await worktreeStatus(child.worktree).catch(() => undefined);
+        if (status?.clean)
+            return undefined;
+        const what = status
+            ? [status.commits ? `${status.commits} commit(s)` : "", status.changes.length ? `${status.changes.length} changed file(s)` : ""]
+                .filter(Boolean)
+                .join(", ")
+            : "changes";
+        const worktree = child.worktree;
+        const where = worktree.branch ? `${worktree.path} on branch ${worktree.branch}` : `${worktree.path} (a copy of the folder)`;
+        return `The subagent worked in ${where} and left ${what} there.`;
+    }
+    /**
+     * A subagent is finished with: its browser and computer go, and a worktree
+     * it changed nothing in is removed. One that it changed is kept — the
+     * parent has to decide what happens to that work.
+     */
+    async disposeChild(child) {
+        await child.equipment?.release().catch(() => { });
+        if (child.worktree)
+            await this.dropIfUntouched(child.worktree);
+    }
+    async dropIfUntouched(worktree) {
+        const status = await worktreeStatus(worktree).catch(() => undefined);
+        if (status?.clean)
+            await finishWorktree(worktree, "remove").catch(() => { });
     }
     // --- Main loop ----------------------------------------------------------
     async *run(input, runOpts = {}) {
@@ -338,7 +782,10 @@ export class Agent {
                 yield { type: "notice", message: start.additionalContext };
             }
         }
-        const maxTurns = this.opts.maxTurns ?? DEFAULT_MAX_TURNS;
+        const baseMaxTurns = this.opts.maxTurns ?? DEFAULT_MAX_TURNS;
+        // Read per turn rather than once: a goal can be reached, or reported
+        // blocked, partway through the run, and the ordinary ceiling returns then.
+        const turnLimit = () => (activeGoal(this.state) ? Math.max(baseMaxTurns, GOAL_MAX_TURNS) : baseMaxTurns);
         let stopReason = "end_turn";
         let turn = 0;
         const finishRun = this.opts.onRunStart?.();
@@ -359,7 +806,13 @@ export class Agent {
                 yield { type: "memory_extracted", notes: extracted };
             }
             yield* this.ingestInput(input);
-            while (turn < maxTurns) {
+            // Background results that ended since the last run ride along with
+            // whatever started this one. A run started only to read them in is
+            // given no input of its own, and has nothing to answer if another path
+            // got to them first.
+            const noticed = yield* this.takeNotices();
+            const nothingToAnswer = Array.isArray(input) && input.length === 0 && !noticed;
+            while (!nothingToAnswer && turn < turnLimit()) {
                 if (signal.aborted) {
                     stopReason = "aborted";
                     break;
@@ -428,15 +881,28 @@ export class Agent {
                     // rather than ending and starting a new run keeps one turn's worth
                     // of context, and matches what the user saw: they typed it before
                     // the reply landed.
-                    if (!signal.aborted && (yield* this.takeInbox()))
-                        continue;
+                    if (!signal.aborted) {
+                        const said = yield* this.takeInbox();
+                        const noticed = yield* this.takeNotices();
+                        if (said || noticed)
+                            continue;
+                    }
                     stopReason = assembled.stopReason === "tool_use" ? "end_turn" : assembled.stopReason;
+                    if (!signal.aborted && (yield* this.pushTowardGoal()))
+                        continue;
                     break;
                 }
+                const goalBefore = activeGoal(this.state);
                 const results = [];
                 for await (const event of this.executeCalls(calls, signal, results)) {
                     yield event;
                 }
+                // The goal tool settles the goal in place; saying so here is what lets
+                // a UI take down its "working toward" line the moment it is done.
+                if (goalBefore && goalBefore.status !== "active") {
+                    yield { type: "goal", goal: { ...goalBefore } };
+                    void this.session.persist().catch(() => { });
+                }
                 // All tool results for a turn must go back in one user message —
                 // splitting them teaches the model to stop calling tools in parallel.
                 await this.session.addMessage({
@@ -452,8 +918,10 @@ export class Agent {
                 // reaches here before it notices and would read a message it is about
                 // to stop answering, leaving it in the transcript with no reply. Left
                 // in the inbox it goes back to the composer instead.
-                if (!signal.aborted)
+                if (!signal.aborted) {
                     yield* this.takeInbox();
+                    yield* this.takeNotices();
+                }
                 if (this.stopRequested) {
                     yield { type: "notice", message: this.stopRequested };
                     this.stopRequested = undefined;
@@ -465,10 +933,10 @@ export class Agent {
                     break;
                 }
             }
-            if (turn >= maxTurns && stopReason === "end_turn") {
+            if (turn >= turnLimit() && stopReason === "end_turn") {
                 yield {
                     type: "notice",
-                    message: `Stopped after ${maxTurns} turns without finishing. Send another message to continue.`,
+                    message: `Stopped after ${turn} turns without finishing. Send another message to continue.`,
                 };
             }
             await this.hooks.run({
@@ -491,6 +959,12 @@ export class Agent {
             this.running = false;
             await this.session.persist().catch(() => { });
             finishRun?.();
+            // Results that ended after the loop's last look. Not after an interrupt:
+            // the person just said stop, and a turn starting by itself half a second
+            // later would be the agent ignoring them. They ride along with the next
+            // run instead, or wake one when another task ends.
+            if (stopReason !== "aborted" && this.background?.hasUndelivered())
+                this.scheduleWake();
         }
         yield {
             type: "done",
@@ -501,6 +975,32 @@ export class Agent {
         };
     }
     // --- Steps --------------------------------------------------------------
+    /**
+     * Where a reply ends with a goal still active: ask for more work.
+     *
+     * Returns whether the loop should go on. A model that keeps stopping short
+     * of its goal gets a bounded number of reminders, not an endless supply.
+     */
+    async *pushTowardGoal() {
+        const goal = activeGoal(this.state);
+        if (!goal)
+            return false;
+        if (goal.nudges >= MAX_GOAL_NUDGES) {
+            yield {
+                type: "notice",
+                message: `Goal still open after ${MAX_GOAL_NUDGES} reminders; stopping here. Send a message to keep going.`,
+            };
+            return false;
+        }
+        goal.nudges++;
+        await this.session.addMessage({
+            role: "user",
+            content: [{ type: "text", text: goalNudge(goal) }],
+            meta: { timestamp: Date.now(), synthetic: true, goalNudge: true },
+        });
+        yield { type: "goal", goal: { ...goal } };
+        return true;
+    }
     async *ingestInput(input) {
         if (Array.isArray(input)) {
             for (const message of input)
@@ -675,11 +1175,75 @@ export class Agent {
         const length = this.session.messages.length;
         return Number.isSafeInteger(value) && value >= 0 ? Math.min(value, length) : length;
     }
-    async *maybeCompact() {
-        if (this.opts.compaction === false)
+    /**
+     * How full the model's window is, in tokens: what the last request measured,
+     * or, before one has (a new or reopened conversation), an estimate of the
+     * next request — system prompt and tools included, which are a large share
+     * of a short conversation.
+     */
+    contextTokens() {
+        return this.contextBreakdown().total;
+    }
+    /**
+     * The window, split the way the context panel draws it. Providers report one
+     * number for the prompt, so the system prompt and the tool definitions are
+     * estimated and the messages are what is left of the measured total; until
+     * something is measured all three are estimates.
+     */
+    contextBreakdown() {
+        const window = this.session.model.contextWindow;
+        // Kept per transcript: the terminal asks on every frame it draws, and the
+        // prompt is rebuilt from skills, memory and plugins each time it is made.
+        const transcript = this.session.messages;
+        let estimate = this.contextEstimate;
+        if (!estimate || estimate.messages !== transcript || estimate.length !== transcript.length) {
+            const request = this.buildRequest(new AbortController().signal);
+            estimate = {
+                messages: transcript,
+                length: transcript.length,
+                system: estimateStringTokens(request.system ?? ""),
+                tools: request.tools ? estimateToolsTokens(request.tools) : 0,
+                transcript: estimateMessagesTokens(transcript),
+            };
+            this.contextEstimate = estimate;
+        }
+        const measured = this.session.measuredContextTokens();
+        const fixed = estimate.system + estimate.tools;
+        const total = measured ?? fixed + estimate.transcript;
+        const compaction = this.opts.compaction;
+        return {
+            total,
+            window,
+            system: estimate.system,
+            tools: estimate.tools,
+            messages: Math.max(0, total - fixed),
+            measured: measured !== undefined,
+            // Where the automatic kind fires: a share of what is left once the
+            // reply has been given room (see shouldCompact).
+            ...(compaction === false
+                ? {}
+                : { compactAt: compactionPoint(this.session.model, compaction?.threshold) }),
+        };
+    }
+    contextEstimate;
+    /**
+     * Compact now, whatever the window says: the /compact command. Goes through
+     * the same path as the automatic kind, so what it drops is archived for
+     * recall and handed to memory extraction rather than simply discarded.
+     * Returns what happened, or undefined when there was nothing safe to cut.
+     */
+    async compactNow() {
+        let last;
+        for await (const event of this.maybeCompact(true))
+            last = event;
+        return last;
+    }
+    async *maybeCompact(manual = false) {
+        if (!manual && this.opts.compaction === false)
             return;
         const systemTokens = estimateStringTokens(this.systemPrompt());
-        if (!shouldCompact(this.session.messages, this.session.model, systemTokens, this.opts.compaction)) {
+        const options = this.opts.compaction || {};
+        if (!manual && !shouldCompact(this.session.messages, this.session.model, systemTokens, options)) {
             return;
         }
         await this.hooks.run({
@@ -695,7 +1259,9 @@ export class Agent {
             // the session happens to be using.
             const summarizer = this.summarizerModel();
             const provider = this.session.providers.getProvider(summarizer.provider);
-            const result = await compact(this.session.messages, provider, summarizer, this.opts.compaction ?? {});
+            const result = await compact(this.session.messages, provider, summarizer, 
+            // Asked for by name, so keep less of the tail: the person wants room.
+            manual ? { ...options, keepTailFraction: 0.15 } : options);
             if (result.droppedMessages === 0)
                 return;
             // Read before the transcript changes shape: the marker is a position in it.
@@ -723,7 +1289,23 @@ export class Agent {
             yield { type: "notice", message: `Compaction failed: ${errorMessage(err)}` };
         }
     }
+    /**
+     * The tools offered to the model: the goal tool only while there is a goal,
+     * and the computer tools only while this conversation has Computer Use on.
+     */
+    visibleTools() {
+        const goal = activeGoal(this.state);
+        const computer = computerOn(this.state);
+        const worktrees = Boolean(this.opts.worktreeLauncher?.());
+        const background = this.backgroundAvailable();
+        return this.tools
+            .visible(this.opts.toolFilter)
+            .filter((tool) => (goal || tool.name !== GOAL_TOOL) && (computer || !isComputerTool(tool.name)))
+            .filter((tool) => worktrees || tool.name !== WORKTREE_START_TOOL)
+            .filter((tool) => background || ![TASK_OUTPUT_TOOL, TASK_STOP_TOOL, TASK_MESSAGE_TOOL].includes(tool.name));
+    }
     systemPrompt() {
+        const goal = activeGoal(this.state);
         return buildSystemPrompt({
             systemPrompt: this.opts.systemPrompt,
             appendSystemPrompt: this.opts.appendSystemPrompt,
@@ -732,10 +1314,16 @@ export class Agent {
             permissionMode: this.session.permissions.getMode(),
             projectInstructions: this.opts.projectInstructions,
             mcpInstructions: this.opts.mcp?.serverInstructions(),
-            toolNames: this.tools.visible(this.opts.toolFilter).map((t) => t.name),
+            toolNames: this.visibleTools().map((t) => t.name),
             // Only the descriptions — loading every skill body up front would
             // defeat the point of having them be loadable.
-            extraSections: [this.skills.promptSection(), this.memoryIndex, ...this.pluginSections].filter((section) => section !== undefined),
+            extraSections: [
+                this.skills.promptSection(),
+                this.memoryIndex,
+                ...this.pluginSections,
+                ...(goal ? [goalPromptSection(goal)] : []),
+                ...(computerOn(this.state) && this.tools.has("computer_list_apps") ? [computerPromptSection()] : []),
+            ].filter((section) => section !== undefined),
         });
     }
     buildRequest(signal) {
@@ -744,7 +1332,13 @@ export class Agent {
             model,
             system: this.systemPrompt(),
             messages: this.session.messages,
-            tools: model.supportsTools ? this.tools.schemas(this.opts.toolFilter) : undefined,
+            tools: model.supportsTools
+                ? this.visibleTools().map((tool) => ({
+                    name: tool.name,
+                    description: tool.description,
+                    inputSchema: tool.inputSchema,
+                }))
+                : undefined,
             toolChoice: { type: "auto" },
             thinking: thinkingFor(this.opts.thinking, this.session.effort),
             cache: this.opts.cache ?? true,
@@ -814,7 +1408,10 @@ export class Agent {
         // concurrently — one unsafe call forces the whole batch to serialize,
         // because we cannot know how they interact.
         const parallel = calls.length > 1 &&
-            calls.every((call) => this.tools.get(call.name)?.concurrencySafe === true);
+            calls.every((call) => {
+                const tool = this.tools.get(call.name);
+                return tool?.concurrencySafe === true || tool?.concurrencySafeFor?.(call.input, this) === true;
+            });
         if (!parallel) {
             for (const call of calls) {
                 yield* this.executeOne(call, signal, results);
@@ -883,18 +1480,24 @@ export class Agent {
             this.stopRequested = reason;
             return;
         }
-        // The workspace policy runs before the approval prompt: a write the
-        // policy forbids should never be offered for approval at all.
+        // The workspace policy runs before the approval prompt. A write outside
+        // the roots is a question for the person, not a refusal: they are the one
+        // who knows whether that folder is fair game, and the answer to it stands
+        // in for the ordinary approval. A read-only workspace, plan mode, or no
+        // one to ask still refuses outright.
+        let approved = false;
         if (this.opts.workspace && !tool.readOnly) {
             const check = checkWrite(this.opts.workspace, call.name, input, this.session.cwd);
             if (!check.allowed) {
-                const reason = check.reason ?? "blocked by the workspace policy";
-                yield { type: "permission_result", toolCallId: call.id, allowed: false, reason };
-                results.push(errorResult(call, reason));
-                return;
+                const outside = yield* this.askOutsideRoots(call, input, title, check, signal);
+                if (!outside) {
+                    results.push(errorResult(call, check.reason ?? "blocked by the workspace policy"));
+                    return;
+                }
+                approved = true;
             }
         }
-        const allowed = yield* this.checkPermission(call, tool, input, title, signal);
+        const allowed = approved || (yield* this.checkPermission(call, tool, input, title, signal));
         if (!allowed)
             return void results.push(errorResult(call, permissionDenialText(title)));
         const ctx = {
@@ -1021,6 +1624,38 @@ export class Agent {
             isError: result.isError,
         });
     }
+    /**
+     * Ask about a write the workspace policy would refuse.
+     *
+     * Bypass mode approves it as it approves everything else. Read-only and plan
+     * mode refuse it, as does a frontend with no way to ask.
+     */
+    async *askOutsideRoots(call, input, title, check, signal) {
+        const mode = this.session.permissions.getMode();
+        const refuse = function* (reason) {
+            yield { type: "permission_result", toolCallId: call.id, allowed: false, reason };
+            return false;
+        };
+        if (this.opts.workspace?.mode === "read-only" || mode === "plan" || !this.opts.permissionPrompt) {
+            return yield* refuse(check.reason ?? "blocked by the workspace policy");
+        }
+        if (mode === "bypassPermissions")
+            return true;
+        const request = {
+            toolName: call.name,
+            input,
+            title,
+            reason: `Writes outside the project: ${check.offending ?? ""}`.trim(),
+            ...this.interactionPlace(),
+            toolCallId: call.id,
+        };
+        yield { type: "permission_request", request };
+        const prompt = this.opts.permissionPrompt;
+        const answer = await untilAborted(signal, () => prompt(request, signal), false, false);
+        const allowed = typeof answer === "boolean" ? answer : answer.allow;
+        yield { type: "permission_result", toolCallId: call.id, allowed };
+        return allowed;
+    }
     async *checkPermission(call, tool, input, title, signal) {
         const decision = this.session.permissions.evaluate(tool, input);
         if (decision.behavior === "allow")
@@ -1031,6 +1666,7 @@ export class Agent {
                 toolCallId: call.id,
                 allowed: false,
                 reason: decision.message,
+                ...(decision.rule === "plan" ? { plan: true } : {}),
             };
             return false;
         }
@@ -1040,7 +1676,7 @@ export class Agent {
             title,
             reason: decision.rule ? `matched rule ${decision.rule}` : undefined,
             ...(decision.rule ? { rule: decision.rule } : {}),
-            sessionId: this.session.id,
+            ...this.interactionPlace(),
             toolCallId: call.id,
         };
         yield { type: "permission_request", request };