@oharness/engine 0.9.3 → 0.11.0

package/dist/agent/agent.js

@@ -1,17 +1,26 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { GOAL_MAX_TURNS, GOAL_TOOL, MAX_GOAL_NUDGES, activeGoal, goalNudge, goalPromptSection, goalTool } from "./goal.js";
+import { COMPUTER_ENABLE_TOOL, 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";
@@ -21,9 +30,21 @@ import { createSkillTool } from "../tools/builtin/skill.js";
 import { createMcpResourceTools } from "../tools/builtin/mcp-resource.js";
 import { HookRegistry } from "./hooks.js";
 import { buildSystemPrompt } from "./prompt.js";
+import { AcpSignInRequired, AcpUnavailable, runAcpTurn } from "../acp/runner.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 +78,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 +108,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 +153,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 +277,389 @@ 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({
+        // Nor may it switch the screen on for itself; see the COMPUTER_KEY rule above.
+        childTools.unregister(COMPUTER_ENABLE_TOOL);
+        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,41 +668,372 @@ 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) {
+        if (child.definition.runtime?.kind === "acp")
+            return this.runExternalChild(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 } };
+    }
+    /**
+     * One run of a subagent whose loop is an external agent's (ACP).
+     *
+     * The child session is still kept, as the record of the task: the prompt
+     * and the agent's answer go into it, so a background task's transcript and
+     * a follow-up after a restart read the same as any other subagent's. The
+     * agent itself starts fresh each run, so what came before rides in the
+     * prompt.
+     */
+    async runExternalChild(child, input, signal, report) {
+        const runtime = child.definition.runtime;
+        const session = child.agent.session;
+        const earlier = session.messages
+            .map((message) => `${message.role === "user" ? "Asked" : "You answered"}: ${messageText(message).trim()}`)
+            .filter((line) => !line.endsWith(": "));
+        const prompt = earlier.length
+            ? `Earlier in this task:\n\n${earlier.join("\n\n")}\n\nNow: ${input}`
+            : input;
+        // The agent's own session from the last run, when it ran in this folder:
+        // a follow-up resumes it, so the agent keeps what it learned, and only
+        // the new message is sent. Another folder (a replaced worktree) is not
+        // the same session, whatever its id.
+        const last = [...session.messages].reverse().find((message) => message.role === "assistant");
+        const previous = last?.meta?.["acpSession"];
+        const resume = typeof previous?.id === "string" && previous.cwd === session.cwd
+            ? { sessionId: previous.id, prompt: input }
+            : undefined;
+        const servers = await this.forwardedMcpServers();
+        await session.addMessage({ role: "user", content: [{ type: "text", text: input }], meta: { timestamp: Date.now() } });
+        report?.turn();
+        let text;
+        let acpSession;
+        try {
+            const result = await runAcpTurn({
+                runtime,
+                cwd: session.cwd,
+                prompt,
+                ...(resume ? { resume } : {}),
+                ...(servers.length ? { mcpServers: servers } : {}),
+                // Its file reads and writes through the same policy as ours: in the
+                // project (or its worktree), and nowhere it was not allowed to go.
+                fs: child.agent.externalFs(),
+                ...(signal ? { signal } : {}),
+                askPermission: (title, toolInput, toolCallId) => child.agent.askForExternal(title, toolInput, toolCallId, signal),
+                onActivity: (title) => report?.activity(title),
+            });
+            text = result.text || (result.stopReason === "cancelled" ? "Stopped." : "The agent finished without saying anything.");
+            acpSession = { id: result.sessionId, cwd: session.cwd };
+        }
+        catch (err) {
+            // Said as the answer rather than thrown: "sign in to Claude Code" is
+            // what the parent has to pass on, not a crash to report.
+            if (err instanceof AcpSignInRequired || err instanceof AcpUnavailable)
+                text = err.message;
+            else
+                throw err;
+        }
+        await session.addMessage({
+            role: "assistant",
+            content: [{ type: "text", text }],
+            meta: { timestamp: Date.now(), ...(acpSession ? { acpSession } : {}) },
+        });
+        await this.hooks.run({
+            event: "SubagentStop",
+            sessionId: this.session.id,
+            agentId: `${this.agentId}/${child.definition.name}`,
             cwd: this.session.cwd,
         });
+        // No usage: the external agent bills its own account and reports none.
+        return { text, turns: 1, usage: { inputTokens: 0, outputTokens: 0 } };
+    }
+    /**
+     * File access for an external agent, through this agent's workspace policy:
+     * reads where ours may read, writes where ours may write, nowhere else.
+     */
+    externalFs() {
         return {
-            text,
-            turns,
-            usage: { inputTokens: usage.inputTokens, outputTokens: usage.outputTokens },
+            read: async (file, line, limit) => {
+                const text = await readFile(this.resolvePath(file, "read"), "utf8");
+                if (line === undefined && limit === undefined)
+                    return text;
+                const lines = text.split("\n");
+                const start = Math.max(0, (line ?? 1) - 1);
+                return lines.slice(start, limit === undefined ? undefined : start + limit).join("\n");
+            },
+            write: async (file, content) => {
+                const target = this.resolvePath(file, "write");
+                await mkdir(path.dirname(target), { recursive: true });
+                await writeFile(target, content);
+            },
         };
     }
+    /**
+     * `@claude …`: a message addressed to an external agent by name.
+     *
+     * Only an agent with an ACP runtime answers to this, and only at the start
+     * of what was typed — or of the paragraph after a reference note, which the
+     * page puts above the prompt. The note stays with the message; the name
+     * does not.
+     */
+    directTarget(input) {
+        if (typeof input !== "string")
+            return undefined;
+        const match = /(^|\n\n)@([\w./-]+)[ \t]+(\S[\s\S]*)$/.exec(input);
+        if (!match)
+            return undefined;
+        const definition = this.subagents.get(match[2]);
+        if (definition?.runtime?.kind !== "acp")
+            return undefined;
+        const note = input.slice(0, match.index).trim();
+        return { definition, text: note ? `${note}\n\n${match[3]}` : match[3] };
+    }
+    /**
+     * A turn answered by an external agent instead of the model.
+     *
+     * What makes `@claude` worth having: the message goes straight to the
+     * user's own Claude Code, so it is paid for by their Claude account and
+     * nothing is spent on this harness's model in between. The agent's reply
+     * streams into the conversation as text, its tool calls as tool cards, its
+     * questions as the usual permission card; the exchange is kept as an
+     * ordinary user/assistant pair, and the agent's session id rides on the
+     * reply so the next `@claude` picks up where this one left off.
+     */
+    async *runDirect(target, raw, signal) {
+        const { definition, text } = target;
+        const runtime = definition.runtime;
+        const finishRun = this.opts.onRunStart?.();
+        let stopReason = "end_turn";
+        try {
+            await this.session.init();
+            await this.session.addMessage(userMessage(raw));
+            yield { type: "turn_start", turn: 1, model: definition.name };
+            const previous = [...this.session.messages]
+                .reverse()
+                .find((message) => message.role === "assistant" && message.meta?.["agent"] === definition.name)
+                ?.meta?.["acpSession"];
+            const resume = typeof previous?.id === "string" && previous.cwd === this.session.cwd
+                ? { sessionId: previous.id, prompt: text }
+                : undefined;
+            const events = channel();
+            const started = new Map();
+            let reply = "";
+            const servers = await this.forwardedMcpServers();
+            const turn = runAcpTurn({
+                runtime,
+                cwd: this.session.cwd,
+                prompt: text,
+                ...(resume ? { resume } : {}),
+                ...(servers.length ? { mcpServers: servers } : {}),
+                fs: this.externalFs(),
+                signal,
+                askPermission: (title, input, toolCallId) => this.askForExternal(title, input, toolCallId, signal, definition.name),
+                onActivity: (title) => {
+                    if (title === "Starting the agent…")
+                        events.push({ type: "notice", message: `Starting ${definition.name}…` });
+                },
+                onUpdate: (update) => {
+                    if (update.sessionUpdate === "agent_message_chunk" || update.sessionUpdate === "agent_thought_chunk") {
+                        const content = update.content;
+                        if (content?.type !== "text" || !content.text)
+                            return;
+                        if (update.sessionUpdate === "agent_thought_chunk")
+                            return events.push({ type: "thinking_delta", text: content.text });
+                        reply += content.text;
+                        events.push({ type: "text_delta", text: content.text });
+                    }
+                    else if (update.sessionUpdate === "tool_call") {
+                        const call = update;
+                        const id = `${definition.name}:${call.toolCallId}`;
+                        started.set(id, Date.now());
+                        events.push({
+                            type: "tool_start",
+                            toolCallId: id,
+                            toolName: call.kind || "tool",
+                            title: call.title || call.kind || "tool",
+                            input: call.rawInput ?? {},
+                        });
+                    }
+                    else if (update.sessionUpdate === "tool_call_update") {
+                        const call = update;
+                        const id = `${definition.name}:${call.toolCallId}`;
+                        if ((call.status !== "completed" && call.status !== "failed") || !started.has(id))
+                            return;
+                        const began = started.get(id);
+                        started.delete(id);
+                        events.push({
+                            type: "tool_end",
+                            toolCallId: id,
+                            toolName: call.kind || "tool",
+                            result: { content: [{ type: "text", text: call.status }], ...(call.status === "failed" ? { isError: true } : {}) },
+                            durationMs: Date.now() - began,
+                        });
+                    }
+                },
+            });
+            void turn.then(() => events.close(), () => events.close());
+            for await (const event of events.drain())
+                yield event;
+            let acpSession;
+            try {
+                const result = await turn;
+                acpSession = { id: result.sessionId, cwd: this.session.cwd };
+                if (result.stopReason === "cancelled" || signal.aborted)
+                    stopReason = "aborted";
+                if (!reply.trim())
+                    reply = result.text;
+            }
+            catch (err) {
+                if (err instanceof AcpSignInRequired || err instanceof AcpUnavailable) {
+                    reply = err.message;
+                    yield { type: "text_delta", text: err.message };
+                }
+                else if (signal.aborted) {
+                    stopReason = "aborted";
+                }
+                else {
+                    stopReason = "error";
+                    yield { type: "error", error: `${definition.name}: ${errorMessage(err)}`, fatal: false };
+                }
+            }
+            if (reply.trim()) {
+                const message = {
+                    role: "assistant",
+                    content: [{ type: "text", text: reply }],
+                    meta: { timestamp: Date.now(), agent: definition.name, ...(acpSession ? { acpSession } : {}) },
+                };
+                await this.session.addMessage(message);
+                yield { type: "assistant_message", message };
+            }
+        }
+        finally {
+            this.running = false;
+            await this.session.persist().catch(() => { });
+            finishRun?.();
+        }
+        yield { type: "done", stopReason, usage: this.session.usage, costUsd: this.session.costUsd, turns: 1 };
+    }
+    /**
+     * This conversation's MCP servers, in the shape ACP's `session/new` takes,
+     * so an external agent works with the same tools. HTTP ones are filtered
+     * out later for an agent that does not take them.
+     */
+    async forwardedMcpServers() {
+        const pairs = (values) => Object.entries(values ?? {}).map(([name, value]) => ({ name, value }));
+        const found = await this.opts.mcp?.forwardable().catch(() => []) ?? [];
+        return found.map(({ name, config, headers }) => config.type === "stdio"
+            ? { name, command: config.command, args: config.args ?? [], env: pairs(config.env) }
+            : { type: "http", name, url: config.url, headers: pairs({ ...config.headers, ...headers }) });
+    }
+    /**
+     * An external agent's own tool call, put to the person the way this
+     * harness's calls are — the same card, placed in the conversation that
+     * started the task and labelled with who is asking. Plan mode and a
+     * read-only workspace refuse; bypass allows, as it would for our own tools.
+     */
+    async askForExternal(title, input, toolCallId, signal, from) {
+        const mode = this.session.permissions.getMode();
+        if (this.opts.workspace?.mode === "read-only" || mode === "plan" || !this.opts.permissionPrompt)
+            return false;
+        if (mode === "bypassPermissions")
+            return true;
+        const request = {
+            toolName: "external",
+            input,
+            title,
+            ...this.interactionPlace(),
+            ...(from ? { from } : {}),
+            toolCallId,
+        };
+        const prompt = this.opts.permissionPrompt;
+        const ask = () => prompt(request, signal);
+        return signal ? untilAborted(signal, ask, false, false) : ask();
+    }
+    /** 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 = {}) {
         this.running = true;
@@ -323,6 +1047,12 @@ export class Agent {
             this.running = false;
             throw new Error("Agent host is closed");
         }
+        // Addressed to an external agent by name: its turn, not the model's.
+        const direct = this.directTarget(input);
+        if (direct) {
+            yield* this.runDirect(direct, input, signal);
+            return;
+        }
         // Fired once per session rather than per turn: hooks use it to seed
         // context or announce the session, which should not repeat every prompt.
         if (!this.sessionStarted) {
@@ -338,7 +1068,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 +1092,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 +1167,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 +1204,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 +1219,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 +1245,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 +1261,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 +1461,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 +1545,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 +1575,26 @@ 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)))
+            // Asking for the computer is for a conversation without it and with
+            // somebody there: a routine or a headless run has nobody to answer.
+            .filter((tool) => tool.name !== COMPUTER_ENABLE_TOOL || (!computer && Boolean(this.opts.permissionPrompt)))
+            .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 +1603,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 +1621,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 +1697,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 +1769,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 +1913,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 +1955,7 @@ export class Agent {
                 toolCallId: call.id,
                 allowed: false,
                 reason: decision.message,
+                ...(decision.rule === "plan" ? { plan: true } : {}),
             };
             return false;
         }
@@ -1040,7 +1965,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 };
@@ -1142,4 +2067,36 @@ function touchesSkills(toolName, input) {
     // what is advertised, so re-scanning for those would be noise.
     return target.includes("skills") && target.endsWith("SKILL.md");
 }
+/**
+ * A queue a callback pushes into and a generator drains, for turning an
+ * external agent's callbacks into a stream of events as they happen.
+ */
+function channel() {
+    const items = [];
+    let wake;
+    let closed = false;
+    const poke = () => {
+        wake?.();
+        wake = undefined;
+    };
+    return {
+        push(item) {
+            items.push(item);
+            poke();
+        },
+        close() {
+            closed = true;
+            poke();
+        },
+        async *drain() {
+            for (;;) {
+                while (items.length)
+                    yield items.shift();
+                if (closed)
+                    return;
+                await new Promise((resolve) => (wake = resolve));
+            }
+        },
+    };
+}
 //# sourceMappingURL=agent.js.map