hoomanjs 1.35.2 → 1.36.0

package/dist/acp/acp-agent.js

@@ -2,38 +2,86 @@ import path from "node:path";
 import { readFile } from "node:fs/promises";
 import { Readable, Writable } from "node:stream";
 import { stdin, stdout } from "node:process";
-import { AgentSideConnection, ndJsonStream, PROTOCOL_VERSION, RequestError, } from "@agentclientprotocol/sdk";
+import { agent as acpAgent, methods, ndJsonStream, PROTOCOL_VERSION, RequestError, } from "@agentclientprotocol/sdk";
 import { isModelStreamEvent, Message, } from "@strands-agents/sdk";
 import { bootstrap } from "../core/index.js";
+import { applySessionMode } from "../core/agent/sync-tool-registry-mode.js";
+import { MODE_DEFINITIONS } from "../core/modes/definitions.js";
+import { DEFAULT_SESSION_MODE, isKnownSessionMode, } from "../core/modes/schema.js";
+import { getModeState, setSessionMode } from "../core/state/session-mode.js";
+import { isYoloEnabled, setYoloEnabled } from "../core/state/yolo.js";
+import { getAgentConversationManager, getAgentSessionManager, } from "../core/agent/index.js";
+import { readBundledPrompt } from "../core/prompts/bundled.js";
+import { formatModeNames } from "../core/modes/definitions.js";
+import { modelProviders } from "../core/models/index.js";
+import { buildSessionConfigOptions, currentModelName, CONFIG_ID_MODE, CONFIG_ID_MODEL, } from "./session-config.js";
+import { ACP_SLASH_COMMANDS, parseAcpSlashCommand, parseYoloToggle, } from "./commands.js";
+import { ENTER_PLAN_MODE_TOOL, EXIT_PLAN_MODE_TOOL, } from "../core/state/tool-approvals.js";
 import { runWithCwd } from "../core/utils/cwd-context.js";
+import { runWithAgentMemoryScope } from "../core/memory/index.js";
+import { consumeExitRequest, EXIT_REQUESTED_CODE, } from "../core/state/exit-request.js";
+import { createSessionConfig, } from "../core/session-config.js";
 import { acpSessionsRootPath } from "./utils/paths.js";
 import { inferToolKind } from "./utils/tool-kind.js";
-import { toolResultToAcpContent } from "./utils/tool-result-content.js";
+import { fileToolDiffContent, toolResultToAcpContent, } from "./utils/tool-result-content.js";
+import { toolCallLocationsFromInput } from "./utils/tool-locations.js";
+import { takeFileToolDisplay } from "../core/state/file-tool-display.js";
+import { getTodoViewState } from "../core/state/todos.js";
+import { UPDATE_TODOS_TOOL_NAME } from "../core/tools/todo.js";
+import { setTextFsBackend } from "../core/tools/text-fs-backend.js";
+import { setTerminalBackend, } from "../core/tools/terminal-backend.js";
 import { createAcpToolApprovalIntervention } from "./approvals.js";
-import { replayConversationHistory } from "./sessions/replay.js";
-import { applySessionConfigOption, buildSessionConfigOptions, HOOMAN_SESSION_MODE_CONFIG_ID, HOOMAN_YOLO_CONFIG_ID, } from "./sessions/options.js";
-import { applySessionMode } from "../core/agent/sync-tool-registry-mode.js";
-import { copyAgentAppState } from "../core/state/agent-app-state.js";
-import { getModeState } from "../core/state/session-mode.js";
-import { ENTER_PLAN_MODE_TOOL, EXIT_PLAN_MODE_TOOL, } from "../core/state/tool-approvals.js";
-import { isYoloEnabled } from "../core/state/yolo.js";
 import { extractAcpClientUserId } from "./meta/user-id.js";
 import { deriveSessionTitleFromEcho } from "./sessions/title.js";
 import { acpPromptEchoText, acpPromptToInvokeArgs } from "./prompt-invoke.js";
-import { createSessionConfig, } from "../core/session-config.js";
 import { normalizeAcpSessionMcpServers } from "./mcp-servers.js";
-import { consumeExitRequest, EXIT_REQUESTED_CODE, } from "../core/state/exit-request.js";
-import { flushAgentMemory, runWithAgentMemoryScope, } from "../core/memory/index.js";
-import { listStoredSessionIds, loadSessionMessages, patchSessionMeta, readSessionMeta, saveSessionMessages, toSessionInfo, writeSessionMeta, } from "./sessions/store.js";
-const DEFAULT_MODE_ID = "agent";
+import { replayConversationHistory } from "./sessions/replay.js";
+import { deleteStoredSession, listStoredSessionIds, loadSessionMessages, patchSessionMeta, readSessionMeta, saveSessionMessages, toSessionInfo, writeSessionMeta, } from "./sessions/store.js";
+/** Max sessions returned per `session/list` page. */
 const LIST_PAGE_SIZE = 40;
 /** Fallback when a session record is missing (never mutate). */
 const EMPTY_STREAMED_TOOL_CALL_IDS = new Set();
+/** Prompt injected by the `/init` slash command (generates AGENTS.md). */
+const INIT_AGENTS_PROMPT = readBundledPrompt("static", "init.md");
+async function readAgentIdentity() {
+    const packageUrl = new URL("../../package.json", import.meta.url);
+    const pkg = JSON.parse(await readFile(packageUrl, "utf8"));
+    const binName = pkg.bin && typeof pkg.bin === "object"
+        ? Object.keys(pkg.bin)[0]
+        : undefined;
+    return {
+        name: binName ?? pkg.name ?? "hooman",
+        version: pkg.version ?? "0.0.0",
+    };
+}
+/** Clamp the client's requested protocol version to what we implement. */
 function negotiateProtocolVersion(clientVersion) {
     if (!Number.isFinite(clientVersion) || clientVersion < 1) {
         return PROTOCOL_VERSION;
     }
-    return clientVersion > PROTOCOL_VERSION ? PROTOCOL_VERSION : clientVersion;
+    return Math.min(clientVersion, PROTOCOL_VERSION);
+}
+/** Opaque `session/list` cursor: base64-encoded `{ offset }`. */
+function encodeCursor(offset) {
+    return Buffer.from(JSON.stringify({ offset }), "utf8").toString("base64");
+}
+function decodeCursor(cursor) {
+    try {
+        const raw = Buffer.from(cursor, "base64").toString("utf8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.offset === "number" &&
+            Number.isInteger(parsed.offset) &&
+            parsed.offset >= 0) {
+            return parsed.offset;
+        }
+    }
+    catch {
+        /* fall through to the error below */
+    }
+    throw RequestError.invalidParams({
+        cursor,
+        message: "Invalid pagination cursor",
+    });
 }
 function assertAbsolutePath(value, field) {
     const trimmed = value?.trim() ?? "";
@@ -50,6 +98,7 @@ function assertAbsolutePath(value, field) {
         });
     }
 }
+/** Best-effort parse of a streamed tool-input JSON fragment. */
 function parseStreamingToolJson(buffer) {
     try {
         return JSON.parse(buffer);
@@ -58,6 +107,7 @@ function parseStreamingToolJson(buffer) {
         return { _partialJson: buffer };
     }
 }
+/** Whether a thrown error represents cooperative cancellation, not a failure. */
 function isCancellationError(err, cancelSignals) {
     if (cancelSignals.some((s) => s.aborted)) {
         return true;
@@ -68,6 +118,7 @@ function isCancellationError(err, cancelSignals) {
     const e = err;
     return e.name === "AbortError" || e.name === "CancelledError";
 }
+/** Map a Strands stop reason onto the ACP {@link StopReason} vocabulary. */
 function toAcpStopReason(reason) {
     switch (reason) {
         case "cancelled":
@@ -88,149 +139,114 @@ function toAcpStopReason(reason) {
 function serializeAgentMessages(agent) {
     return agent.messages.map((m) => m.toJSON());
 }
-async function readPackageDetails() {
-    const packageUrl = new URL("../../package.json", import.meta.url);
-    const pkg = JSON.parse(await readFile(packageUrl, "utf8"));
-    const commandName = typeof pkg.bin === "string"
-        ? pkg.name
-        : pkg.bin && typeof pkg.bin === "object"
-            ? Object.keys(pkg.bin)[0]
-            : undefined;
+/** Normalize a persisted/requested mode to a known id, else the default. */
+function resolveSessionMode(mode) {
+    return mode && isKnownSessionMode(mode) ? mode : DEFAULT_SESSION_MODE;
+}
+/** The ACP `SessionModeState` advertised for a session's current mode. */
+function buildSessionModeState(currentModeId) {
     return {
-        name: commandName ?? pkg.name ?? "hooman",
-        version: pkg.version ?? "0.0.0",
+        currentModeId,
+        availableModes: MODE_DEFINITIONS.map((mode) => ({
+            id: mode.id,
+            name: mode.name,
+            description: mode.description,
+        })),
     };
 }
-export class AcpAgent {
-    #connection;
+/**
+ * Hooman's ACP agent, built on the app-style SDK API.
+ *
+ * Implements initialization, session setup (`session/new`, `session/load`),
+ * session discovery (`session/list`, `session/delete`), and the full prompt
+ * turn (`session/prompt` streaming + `session/cancel`).
+ */
+export class HoomanAcpAgent {
+    #identity;
+    #acpRoot = acpSessionsRootPath();
     #sessions = new Map();
-    #acpRoot;
-    #version = null;
-    constructor(connection) {
-        this.#connection = connection;
-        this.#acpRoot = acpSessionsRootPath();
-        queueMicrotask(() => {
-            if (connection.signal.aborted) {
-                void this.#disposeAllSessions();
-                return;
-            }
-            connection.signal.addEventListener("abort", () => {
-                void this.#disposeAllSessions();
-            }, { once: true });
-        });
+    /** Connection-scoped outbound context, captured in {@link onConnect}. */
+    #client = null;
+    #connectionSignal = null;
+    /** Client filesystem capabilities from `initialize` (gates `fs/*` calls). */
+    #clientFsCaps = null;
+    /** Whether the client supports `terminal/*` methods (gates the shell tool). */
+    #clientTerminalCap = false;
+    constructor(identity) {
+        this.#identity = identity;
     }
-    async initialize(params) {
-        const { name, version } = await readPackageDetails();
-        this.#version ??= version;
+    /** Bind connection-scoped lifecycle: capture the client + dispose on close. */
+    onConnect(connection) {
+        this.#client = connection.client;
+        this.#connectionSignal = connection.signal;
+        if (connection.signal.aborted) {
+            void this.#disposeAll();
+            return;
+        }
+        connection.signal.addEventListener("abort", () => {
+            void this.#disposeAll();
+        }, { once: true });
+    }
+    initialize(params) {
+        this.#clientFsCaps = params.clientCapabilities?.fs ?? null;
+        this.#clientTerminalCap = params.clientCapabilities?.terminal === true;
         return {
             protocolVersion: negotiateProtocolVersion(params.protocolVersion),
             agentInfo: {
-                name,
-                title: name,
-                version: this.#version,
+                name: this.#identity.name,
+                title: this.#identity.name,
+                version: this.#identity.version,
             },
             authMethods: [],
             agentCapabilities: {
                 loadSession: true,
-                mcpCapabilities: {
-                    http: true,
-                    sse: true,
-                },
                 promptCapabilities: {
-                    embeddedContext: true,
                     image: true,
                     audio: true,
+                    embeddedContext: true,
+                },
+                mcpCapabilities: {
+                    http: true,
+                    sse: true,
                 },
                 sessionCapabilities: {
                     list: {},
+                    delete: {},
                 },
             },
         };
     }
-    async authenticate(_params) {
-        return {};
-    }
-    async setSessionMode(params) {
-        const rec = this.#sessions.get(params.sessionId);
-        if (!rec) {
-            throw RequestError.invalidParams({ sessionId: params.sessionId });
-        }
-        if (!rec.availableModeIds.has(params.modeId)) {
-            throw RequestError.invalidParams({ modeId: params.modeId });
-        }
-        rec.currentModeId = params.modeId;
-        return {};
-    }
-    async setSessionConfigOption(params) {
-        const rec = this.#sessions.get(params.sessionId);
-        if (!rec) {
-            throw RequestError.invalidParams({ sessionId: params.sessionId });
-        }
-        applySessionConfigOption(rec.config, params, rec.agent);
-        if (params.configId === HOOMAN_YOLO_CONFIG_ID) {
-            await patchSessionMeta(this.#acpRoot, params.sessionId, {
-                yolo: isYoloEnabled(rec.agent),
-            });
-        }
-        else if (params.configId === HOOMAN_SESSION_MODE_CONFIG_ID) {
-            await patchSessionMeta(this.#acpRoot, params.sessionId, {
-                sessionMode: getModeState(rec.agent).mode,
-            });
-        }
-        else {
-            rec.agentStale = true;
-        }
-        return {
-            configOptions: buildSessionConfigOptions(rec.config, rec.agent),
-        };
-    }
-    async extMethod(method, _params) {
-        throw RequestError.methodNotFound(method);
-    }
-    async extNotification(_method, _params) {
-        return;
-    }
     async listSessions(params) {
-        void params.additionalDirectories;
         const ids = await listStoredSessionIds(this.#acpRoot);
-        const rows = [];
+        const sessions = [];
         for (const id of ids) {
             const info = await toSessionInfo(this.#acpRoot, id);
-            if (info) {
-                rows.push({ id, info });
-            }
-        }
-        let filtered = rows;
-        if (params.cwd) {
-            filtered = rows.filter((r) => r.info.cwd === params.cwd);
-        }
-        filtered.sort((a, b) => String(b.info.updatedAt ?? "").localeCompare(String(a.info.updatedAt ?? "")));
-        let offset = 0;
-        if (params.cursor) {
-            try {
-                const raw = Buffer.from(params.cursor, "base64").toString("utf8");
-                const o = JSON.parse(raw);
-                offset = Number.isFinite(o.offset) ? Math.max(0, o.offset) : 0;
-            }
-            catch {
-                offset = 0;
+            if (info && (!params.cwd || info.cwd === params.cwd)) {
+                sessions.push(info);
             }
         }
-        const slice = filtered
-            .slice(offset, offset + LIST_PAGE_SIZE)
-            .map((r) => r.info);
+        sessions.sort((a, b) => String(b.updatedAt ?? "").localeCompare(String(a.updatedAt ?? "")));
+        const offset = params.cursor ? decodeCursor(params.cursor) : 0;
+        const page = sessions.slice(offset, offset + LIST_PAGE_SIZE);
         const nextOffset = offset + LIST_PAGE_SIZE;
-        const nextCursor = nextOffset < filtered.length
-            ? Buffer.from(JSON.stringify({ offset: nextOffset }), "utf8").toString("base64")
-            : null;
-        return { sessions: slice, nextCursor };
+        const nextCursor = nextOffset < sessions.length ? encodeCursor(nextOffset) : null;
+        return { sessions: page, nextCursor };
+    }
+    async deleteSession(params) {
+        const record = this.#sessions.get(params.sessionId);
+        if (record) {
+            this.#sessions.delete(params.sessionId);
+            record.turnAbort?.abort();
+            await record.mcpDisconnect();
+        }
+        await deleteStoredSession(this.#acpRoot, params.sessionId);
     }
     async newSession(params) {
         assertAbsolutePath(params.cwd, "cwd");
         const sessionId = crypto.randomUUID();
         const clientUserId = extractAcpClientUserId(params._meta) ?? null;
-        const bootstrapUserId = clientUserId ?? sessionId;
         const mcpServers = normalizeAcpSessionMcpServers(params.mcpServers);
+        const mode = DEFAULT_SESSION_MODE;
         const now = new Date().toISOString();
         const meta = {
             cwd: params.cwd,
@@ -239,59 +255,19 @@ export class AcpAgent {
             title: null,
             userId: clientUserId,
             mcpServers,
+            sessionMode: mode,
         };
         await writeSessionMeta(this.#acpRoot, sessionId, meta);
-        const { config: bootConfig, agent, mcp: { manager }, } = await bootstrap("acp", {
-            userId: bootstrapUserId,
-            sessionId,
-            createInterventions: () => [
-                createAcpToolApprovalIntervention(this.#connection, sessionId, () => this.#sessions.get(sessionId)?.streamedToolCallIds ??
-                    EMPTY_STREAMED_TOOL_CALL_IDS),
-            ],
-            acp: {
-                mcpServers,
-            },
-        }, false, createSessionConfig());
-        const config = bootConfig;
-        const availableModeIds = new Set([DEFAULT_MODE_ID]);
-        this.#sessions.set(sessionId, {
-            cwd: params.cwd,
-            agent,
-            config,
-            currentModeId: DEFAULT_MODE_ID,
-            availableModeIds,
-            mcpDisconnect: async () => {
-                try {
-                    await manager.disconnect();
-                }
-                catch {
-                    /* ignore */
-                }
-            },
-            agentStale: false,
-            turnAbort: null,
-            promptExclusive: Promise.resolve(),
-            streamedToolCallIds: new Set(),
-            streamingToolInputJson: new Map(),
-            lastStreamToolUseId: null,
-        });
+        const record = await this.#bootstrapSession(sessionId, params.cwd, clientUserId ?? sessionId, mcpServers, mode);
+        this.#sessions.set(sessionId, record);
+        await this.#advertiseCommands(this.#requireClient(), sessionId);
         return {
             sessionId,
-            modes: {
-                currentModeId: DEFAULT_MODE_ID,
-                availableModes: [
-                    {
-                        id: DEFAULT_MODE_ID,
-                        name: "Default",
-                        description: "Standard Hooman behaviour for this session.",
-                    },
-                ],
-            },
-            models: null,
-            configOptions: buildSessionConfigOptions(config, agent),
+            modes: buildSessionModeState(mode),
+            configOptions: buildSessionConfigOptions(record.config, mode),
         };
     }
-    async loadSession(params) {
+    async loadSession(params, client) {
         if (this.#sessions.has(params.sessionId)) {
             throw RequestError.invalidParams({
                 sessionId: params.sessionId,
@@ -304,141 +280,328 @@ export class AcpAgent {
         }
         assertAbsolutePath(params.cwd, "cwd");
         const fromRequest = extractAcpClientUserId(params._meta);
-        const storedUserId = existing.userId ?? null;
-        const clientUserId = fromRequest !== undefined ? fromRequest : storedUserId;
-        const bootstrapUserId = clientUserId ?? params.sessionId;
+        const clientUserId = fromRequest !== undefined ? fromRequest : (existing.userId ?? null);
         const mcpServers = params.mcpServers.length > 0
             ? normalizeAcpSessionMcpServers(params.mcpServers)
             : (existing.mcpServers ?? []);
-        const { config: bootConfig, agent, mcp: { manager }, } = await bootstrap("acp", {
-            userId: bootstrapUserId,
-            sessionId: params.sessionId,
-            yolo: existing.yolo === true,
-            mode: existing.sessionMode ?? "agent",
-            createInterventions: () => [
-                createAcpToolApprovalIntervention(this.#connection, params.sessionId, () => this.#sessions.get(params.sessionId)?.streamedToolCallIds ??
-                    EMPTY_STREAMED_TOOL_CALL_IDS),
-            ],
-            acp: {
-                mcpServers,
-            },
-        }, false, createSessionConfig());
-        const config = bootConfig;
+        const mode = resolveSessionMode(existing.sessionMode);
+        const record = await this.#bootstrapSession(params.sessionId, params.cwd, clientUserId ?? params.sessionId, mcpServers, mode, existing.model);
         const saved = await loadSessionMessages(this.#acpRoot, params.sessionId);
-        agent.messages.length = 0;
+        record.agent.messages.length = 0;
         for (const md of saved) {
-            agent.messages.push(Message.fromJSON(md));
+            record.agent.messages.push(Message.fromJSON(md));
         }
-        await replayConversationHistory(this.#connection, params.sessionId, agent.messages);
-        const availableModeIds = new Set([DEFAULT_MODE_ID]);
-        this.#sessions.set(params.sessionId, {
-            cwd: params.cwd,
-            agent,
-            config,
-            currentModeId: DEFAULT_MODE_ID,
-            availableModeIds,
-            mcpDisconnect: async () => {
-                try {
-                    await manager.disconnect();
-                }
-                catch {
-                    /* ignore */
-                }
-            },
-            agentStale: false,
-            turnAbort: null,
-            promptExclusive: Promise.resolve(),
-            streamedToolCallIds: new Set(),
-            streamingToolInputJson: new Map(),
-            lastStreamToolUseId: null,
-        });
+        await replayConversationHistory(client, params.sessionId, record.agent.messages);
+        this.#sessions.set(params.sessionId, record);
         await patchSessionMeta(this.#acpRoot, params.sessionId, {
             cwd: params.cwd,
-            updatedAt: new Date().toISOString(),
             ...(fromRequest !== undefined ? { userId: fromRequest || null } : {}),
             mcpServers,
+            sessionMode: mode,
         });
+        await this.#advertiseCommands(client, params.sessionId);
+        // Surface any restored plan so a resumed session shows its todo list.
+        if (getTodoViewState(record.agent).total > 0) {
+            await this.#sendPlanUpdate(client, params.sessionId, record);
+        }
         return {
-            modes: {
-                currentModeId: DEFAULT_MODE_ID,
-                availableModes: [
-                    {
-                        id: DEFAULT_MODE_ID,
-                        name: "Default",
-                        description: "Standard Hooman behaviour for this session.",
-                    },
-                ],
-            },
-            models: null,
-            configOptions: buildSessionConfigOptions(config, agent),
+            modes: buildSessionModeState(mode),
+            configOptions: buildSessionConfigOptions(record.config, mode),
         };
     }
-    async cancel(params) {
+    /** Advertise the available slash commands for a freshly set-up session. */
+    #advertiseCommands(client, sessionId) {
+        return this.#sendUpdate(client, sessionId, {
+            sessionUpdate: "available_commands_update",
+            availableCommands: [...ACP_SLASH_COMMANDS],
+        });
+    }
+    /**
+     * Handle `session/set_mode`: switch the active mode for a running session,
+     * re-applying the tool surface and persisting the choice.
+     */
+    async setSessionMode(params) {
         const rec = this.#sessions.get(params.sessionId);
         if (!rec) {
-            return;
+            throw RequestError.invalidParams({ sessionId: params.sessionId });
         }
-        rec.turnAbort?.abort();
-        try {
-            rec.agent.cancel();
+        if (!isKnownSessionMode(params.modeId)) {
+            throw RequestError.invalidParams({
+                modeId: params.modeId,
+                message: `Unknown mode "${params.modeId}"`,
+            });
         }
-        catch {
-            /* ignore */
+        if (this.#transitionMode(rec, params.modeId)) {
+            await patchSessionMeta(this.#acpRoot, params.sessionId, {
+                sessionMode: params.modeId,
+            });
         }
+        return {};
     }
-    async #rebuildSessionAgent(sessionId) {
-        const rec = this.#sessions.get(sessionId);
+    /**
+     * Handle `session/set_config_option`: apply a model or mode selection and
+     * return the complete, up-to-date configuration state (as the spec requires).
+     */
+    async setSessionConfigOption(params) {
+        const rec = this.#sessions.get(params.sessionId);
         if (!rec) {
+            throw RequestError.invalidParams({ sessionId: params.sessionId });
+        }
+        if (typeof params.value !== "string") {
+            throw RequestError.invalidParams({
+                configId: params.configId,
+                message: `Config option "${params.configId}" expects a string value`,
+            });
+        }
+        const value = params.value;
+        if (params.configId === CONFIG_ID_MODE) {
+            if (!isKnownSessionMode(value)) {
+                throw RequestError.invalidParams({
+                    value,
+                    message: `Unknown mode "${value}"`,
+                });
+            }
+            if (this.#transitionMode(rec, value)) {
+                await patchSessionMeta(this.#acpRoot, params.sessionId, {
+                    sessionMode: value,
+                });
+            }
+        }
+        else if (params.configId === CONFIG_ID_MODEL) {
+            await this.#applyModelChange(rec, value);
+            await patchSessionMeta(this.#acpRoot, params.sessionId, { model: value });
+        }
+        else {
+            throw RequestError.invalidParams({
+                configId: params.configId,
+                message: `Unknown config option "${params.configId}"`,
+            });
+        }
+        return {
+            configOptions: buildSessionConfigOptions(rec.config, resolveSessionMode(getModeState(rec.agent).mode)),
+        };
+    }
+    /** Whether a prompt turn is currently streaming for this session. */
+    #isTurnActive(rec) {
+        return rec.turnAbort !== null;
+    }
+    /**
+     * Switch the session mode. Records it immediately (so state reads are
+     * correct), but defers the tool-surface rebuild to the next turn boundary
+     * when a turn is streaming, avoiding a mid-turn tool-surface swap. Returns
+     * whether the mode actually changed.
+     */
+    #transitionMode(rec, mode) {
+        if (resolveSessionMode(getModeState(rec.agent).mode) === mode) {
+            return false;
+        }
+        setSessionMode(rec.agent, mode);
+        if (this.#isTurnActive(rec)) {
+            rec.pendingModeReapply = true;
+        }
+        else {
+            applySessionMode(rec.agent);
+        }
+        return true;
+    }
+    /**
+     * Select a new model for the session. Flips the in-memory (ephemeral) config
+     * default immediately, then rebuilds the live model — deferring the rebuild
+     * to the next turn boundary when a turn is streaming.
+     */
+    async #applyModelChange(rec, modelName) {
+        const match = rec.config.llms.find((entry) => entry.name === modelName);
+        if (!match) {
+            throw RequestError.invalidParams({
+                value: modelName,
+                message: `Unknown model "${modelName}"`,
+            });
+        }
+        if (match.name === currentModelName(rec.config)) {
             return;
         }
-        const meta = await readSessionMeta(this.#acpRoot, sessionId);
-        if (!meta) {
+        const previous = currentModelName(rec.config);
+        rec.config.update({
+            llms: rec.config.llms.map((entry) => ({
+                ...entry,
+                default: entry.name === match.name,
+            })),
+        });
+        if (this.#isTurnActive(rec)) {
+            rec.pendingModelRebuild = true;
             return;
         }
-        const bootstrapUserId = meta.userId ?? sessionId;
-        const mcpServers = meta.mcpServers ?? [];
-        const messageSnapshot = serializeAgentMessages(rec.agent);
-        const { config: bootConfig, agent, mcp: { manager }, } = await bootstrap("acp", {
-            userId: bootstrapUserId,
-            sessionId,
-            yolo: isYoloEnabled(rec.agent),
-            mode: getModeState(rec.agent).mode,
-            createInterventions: () => [
-                createAcpToolApprovalIntervention(this.#connection, sessionId, () => this.#sessions.get(sessionId)?.streamedToolCallIds ??
-                    EMPTY_STREAMED_TOOL_CALL_IDS),
-            ],
-            acp: {
-                mcpServers,
-            },
-        }, false, rec.config);
-        const config = bootConfig;
-        agent.messages.length = 0;
-        for (const md of messageSnapshot) {
-            agent.messages.push(Message.fromJSON(md));
-        }
-        copyAgentAppState(rec.agent, agent);
-        applySessionMode(agent);
-        const oldAgent = rec.agent;
-        const oldMcpDisconnect = rec.mcpDisconnect;
-        rec.agent = agent;
-        rec.config = config;
-        rec.mcpDisconnect = async () => {
-            try {
-                await manager.disconnect();
+        await this.#rebuildModel(rec, previous);
+    }
+    /** Rebuild the Strands model from current config, rolling back on failure. */
+    async #rebuildModel(rec, previous) {
+        try {
+            const resolved = rec.config.llm;
+            const provider = await modelProviders[resolved.provider]();
+            rec.agent.model = provider.create(resolved.providerOptions, resolved.llmOptions);
+        }
+        catch (error) {
+            if (previous) {
+                rec.config.update({
+                    llms: rec.config.llms.map((entry) => ({
+                        ...entry,
+                        default: entry.name === previous,
+                    })),
+                });
             }
-            catch {
-                /* ignore */
+            throw RequestError.internalError({
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    /**
+     * Apply settings changes deferred during a turn (mode tool-surface + model
+     * rebuild). Runs at the turn boundary before the next turn may start.
+     */
+    async #flushPendingSettings(rec) {
+        if (rec.pendingModeReapply) {
+            rec.pendingModeReapply = false;
+            applySessionMode(rec.agent);
+        }
+        if (rec.pendingModelRebuild) {
+            rec.pendingModelRebuild = false;
+            await this.#rebuildModel(rec).catch(() => undefined);
+        }
+    }
+    /**
+     * Execute an inline (non-model) slash command and return the text reply to
+     * stream back as an `agent_message_chunk`. `/init` is handled by the caller.
+     */
+    #runControlCommand(client, sessionId, rec, command) {
+        switch (command.name) {
+            case "mode":
+                return this.#commandSetMode(client, sessionId, rec, command.args);
+            case "model":
+                return this.#commandSetModel(client, sessionId, rec, command.args);
+            case "yolo":
+                return this.#commandSetYolo(sessionId, rec, command.args);
+            case "compact":
+                return this.#commandCompact(rec);
+            default:
+                return Promise.resolve(`Unknown command "/${command.name}".`);
+        }
+    }
+    async #commandSetMode(client, sessionId, rec, args) {
+        const current = resolveSessionMode(getModeState(rec.agent).mode);
+        const arg = args.trim().toLowerCase();
+        if (!arg) {
+            return `Usage: /mode <${formatModeNames()}>. Current mode: "${current}".`;
+        }
+        if (!isKnownSessionMode(arg)) {
+            return `Unknown mode "${arg}". Use ${formatModeNames()}.`;
+        }
+        if (!this.#transitionMode(rec, arg)) {
+            return `Already in "${arg}" mode.`;
+        }
+        await this.#syncCurrentMode(client, sessionId, rec);
+        return `Switched session mode to "${arg}".`;
+    }
+    async #commandSetModel(client, sessionId, rec, args) {
+        const arg = args.trim();
+        if (!arg) {
+            return this.#listModelsText(rec);
+        }
+        if (!rec.config.llms.some((entry) => entry.name === arg)) {
+            return `Unknown model "${arg}".\n\n${this.#listModelsText(rec)}`;
+        }
+        if (arg === currentModelName(rec.config)) {
+            return `Already using model "${arg}".`;
+        }
+        try {
+            await this.#applyModelChange(rec, arg);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return `Could not switch to model "${arg}": ${message}`;
+        }
+        await patchSessionMeta(this.#acpRoot, sessionId, { model: arg });
+        await this.#sendUpdate(client, sessionId, {
+            sessionUpdate: "config_option_update",
+            configOptions: buildSessionConfigOptions(rec.config, resolveSessionMode(getModeState(rec.agent).mode)),
+        });
+        return `Switched model to "${arg}".`;
+    }
+    #listModelsText(rec) {
+        const current = currentModelName(rec.config);
+        const lines = rec.config.llms.map((entry) => {
+            const marker = entry.name === current ? "*" : "-";
+            return `${marker} ${entry.name} (${entry.provider}/${entry.options.model})`;
+        });
+        return [
+            `Current model: ${current ?? "(none)"}`,
+            "Available models:",
+            ...lines,
+            'Use "/model <name>" to switch.',
+        ].join("\n");
+    }
+    async #commandSetYolo(sessionId, rec, args) {
+        const arg = args.trim();
+        if (!arg) {
+            return `Usage: /yolo <on|off>. Auto-approve is currently ${isYoloEnabled(rec.agent) ? "on" : "off"}.`;
+        }
+        const enabled = parseYoloToggle(arg);
+        if (enabled === undefined) {
+            return `Unknown value "${arg}". Use on or off.`;
+        }
+        if (isYoloEnabled(rec.agent) === enabled) {
+            return `Auto-approve is already ${enabled ? "on" : "off"}.`;
+        }
+        setYoloEnabled(rec.agent, enabled);
+        await patchSessionMeta(this.#acpRoot, sessionId, { yolo: enabled });
+        return `Auto-approve tools ${enabled ? "enabled" : "disabled"}.`;
+    }
+    async #commandCompact(rec) {
+        const conversationManager = getAgentConversationManager(rec.agent);
+        if (!conversationManager) {
+            return "This session has no conversation manager to compact.";
+        }
+        const before = rec.agent.messages.length;
+        try {
+            const reduced = await conversationManager.reduce({
+                agent: rec.agent,
+                model: rec.agent.model,
+            });
+            if (!reduced) {
+                return "Conversation history is already too short to compact.";
             }
-        };
-        rec.agentStale = false;
-        await flushAgentMemory(oldAgent).catch(() => { });
-        await oldMcpDisconnect();
+            const after = rec.agent.messages.length;
+            await getAgentSessionManager(rec.agent)?.saveSnapshot({
+                target: rec.agent,
+                isLatest: true,
+            });
+            return `Compacted conversation history (${before} → ${after} messages).`;
+        }
+        catch (error) {
+            return error instanceof Error ? error.message : String(error);
+        }
     }
+    /** Cancel an in-flight prompt turn. Silent no-op for unknown sessions. */
+    async cancel(params) {
+        const rec = this.#sessions.get(params.sessionId);
+        if (!rec) {
+            return;
+        }
+        rec.turnAbort?.abort();
+        try {
+            rec.agent.cancel();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    /** Run one prompt turn: stream model output, tool calls, and a stop reason. */
     async prompt(params) {
         const rec = this.#sessions.get(params.sessionId);
         if (!rec) {
             throw RequestError.invalidParams({ sessionId: params.sessionId });
         }
+        const client = this.#requireClient();
+        // Serialize concurrent prompt turns for the same session.
         const prevExclusive = rec.promptExclusive;
         let releaseExclusive;
         const exclusiveGate = new Promise((resolve) => {
@@ -446,9 +609,6 @@ export class AcpAgent {
         });
         rec.promptExclusive = prevExclusive.then(() => exclusiveGate);
         await prevExclusive;
-        if (rec.agentStale) {
-            await this.#rebuildSessionAgent(params.sessionId);
-        }
         const turnAbort = new AbortController();
         rec.turnAbort = turnAbort;
         rec.streamedToolCallIds.clear();
@@ -458,38 +618,48 @@ export class AcpAgent {
         try {
             const echo = acpPromptEchoText(params.prompt);
             if (echo.length > 0) {
-                await this.#connection.sessionUpdate({
-                    sessionId: params.sessionId,
-                    update: {
-                        sessionUpdate: "user_message_chunk",
-                        content: { type: "text", text: echo },
-                    },
+                await this.#sendUpdate(client, params.sessionId, {
+                    sessionUpdate: "user_message_chunk",
+                    content: { type: "text", text: echo },
                 });
-                const meta = await readSessionMeta(this.#acpRoot, params.sessionId);
-                const needsTitle = meta &&
-                    (meta.title === undefined ||
-                        meta.title === null ||
-                        String(meta.title).trim() === "");
-                if (needsTitle) {
-                    const title = deriveSessionTitleFromEcho(echo);
-                    if (title) {
-                        await patchSessionMeta(this.#acpRoot, params.sessionId, { title });
-                        await this.#connection.sessionUpdate({
-                            sessionId: params.sessionId,
-                            update: {
-                                sessionUpdate: "session_info_update",
-                                title,
-                                updatedAt: new Date().toISOString(),
-                            },
-                        });
-                    }
+                await this.#maybeDeriveTitle(client, params.sessionId, echo);
+            }
+            // Slash commands arrive as prompt text. Control commands run inline
+            // (no model turn); `/init` rewrites the prompt and runs normally.
+            const command = parseAcpSlashCommand(echo);
+            if (command && command.name !== "init") {
+                const reply = await this.#runControlCommand(client, params.sessionId, rec, command);
+                if (reply) {
+                    await this.#sendUpdate(client, params.sessionId, {
+                        sessionUpdate: "agent_message_chunk",
+                        content: { type: "text", text: reply },
+                    });
                 }
+                return { stopReason: "end_turn" };
+            }
+            const invokeArgs = command?.name === "init"
+                ? acpPromptToInvokeArgs([
+                    {
+                        type: "text",
+                        text: command.args
+                            ? `${INIT_AGENTS_PROMPT}\n\n${command.args}`
+                            : INIT_AGENTS_PROMPT,
+                    },
+                ])
+                : acpPromptToInvokeArgs(params.prompt);
+            const signals = [turnAbort.signal];
+            if (this.#connectionSignal) {
+                signals.push(this.#connectionSignal);
+            }
+            const cancelSignal = AbortSignal.any(signals);
+            // A new turn resets todos (BeforeInvocationEvent). Clear any stale plan
+            // the client is still showing from the previous turn.
+            if (getTodoViewState(rec.agent).total > 0) {
+                await this.#sendUpdate(client, params.sessionId, {
+                    sessionUpdate: "plan",
+                    entries: [],
+                });
             }
-            const invokeArgs = acpPromptToInvokeArgs(params.prompt);
-            const cancelSignal = AbortSignal.any([
-                this.#connection.signal,
-                turnAbort.signal,
-            ]);
             try {
                 await runWithAgentMemoryScope(rec.agent, async () => {
                     await runWithCwd(rec.cwd, async () => {
@@ -498,32 +668,28 @@ export class AcpAgent {
                         while (!iter.done) {
                             const ev = iter.value;
                             if (ev.type === "modelStreamUpdateEvent") {
-                                await this.#dispatchModelStreamUpdate(params.sessionId, ev, rec);
+                                await this.#dispatchModelStreamUpdate(client, params.sessionId, ev, rec);
                             }
                             else if (ev.type === "afterToolCallEvent") {
-                                await this.#connection.sessionUpdate({
-                                    sessionId: params.sessionId,
-                                    update: {
-                                        sessionUpdate: "tool_call_update",
-                                        toolCallId: ev.toolUse.toolUseId,
-                                        status: ev.result.status === "success" ? "completed" : "failed",
-                                        rawOutput: ev.result.toJSON(),
-                                        content: toolResultToAcpContent(ev.result),
-                                    },
+                                const display = takeFileToolDisplay(rec.agent.appState, ev.toolUse.toolUseId);
+                                const diff = fileToolDiffContent(display);
+                                const locations = toolCallLocationsFromInput(ev.toolUse.name, ev.toolUse.input);
+                                await this.#sendUpdate(client, params.sessionId, {
+                                    sessionUpdate: "tool_call_update",
+                                    toolCallId: ev.toolUse.toolUseId,
+                                    status: ev.result.status === "success" ? "completed" : "failed",
+                                    rawOutput: ev.result.toJSON(),
+                                    content: diff ?? toolResultToAcpContent(ev.result),
+                                    ...(locations ? { locations } : {}),
                                 });
+                                if (ev.toolUse.name === UPDATE_TODOS_TOOL_NAME &&
+                                    ev.result.status === "success") {
+                                    await this.#sendPlanUpdate(client, params.sessionId, rec);
+                                }
                                 if (ev.result.status === "success" &&
                                     (ev.toolUse.name === ENTER_PLAN_MODE_TOOL ||
                                         ev.toolUse.name === EXIT_PLAN_MODE_TOOL)) {
-                                    await patchSessionMeta(this.#acpRoot, params.sessionId, {
-                                        sessionMode: getModeState(rec.agent).mode,
-                                    });
-                                    await this.#connection.sessionUpdate({
-                                        sessionId: params.sessionId,
-                                        update: {
-                                            sessionUpdate: "config_option_update",
-                                            configOptions: buildSessionConfigOptions(rec.config, rec.agent),
-                                        },
-                                    });
+                                    await this.#syncCurrentMode(client, params.sessionId, rec);
                                 }
                             }
                             else if (ev.type === "agentResultEvent") {
@@ -535,32 +701,31 @@ export class AcpAgent {
                 });
             }
             catch (err) {
-                const cancelSignals = [
-                    cancelSignal,
-                    turnAbort.signal,
-                    this.#connection.signal,
-                ];
+                const cancelSignals = [cancelSignal, turnAbort.signal];
                 if (isCancellationError(err, cancelSignals)) {
                     stopReason = "cancelled";
                 }
                 else {
                     const message = err instanceof Error ? err.message : String(err);
-                    await this.#connection.sessionUpdate({
-                        sessionId: params.sessionId,
-                        update: {
-                            sessionUpdate: "agent_message_chunk",
-                            content: {
-                                type: "text",
-                                text: `\n[error] ${message}\n`,
-                            },
-                        },
+                    await this.#sendUpdate(client, params.sessionId, {
+                        sessionUpdate: "agent_message_chunk",
+                        content: { type: "text", text: `\n[error] ${message}\n` },
                     });
                     stopReason = "refusal";
                 }
             }
+            // If cancellation was requested, report `cancelled` even when the stream
+            // happened to finish cleanly right as the signal fired (spec requires the
+            // prompt to resolve with the cancelled stop reason, not `end_turn`).
+            if (turnAbort.signal.aborted) {
+                stopReason = "cancelled";
+            }
         }
         finally {
             rec.turnAbort = null;
+            // Apply mode/model changes requested mid-turn before releasing the gate
+            // so the next turn sees the settled state.
+            await this.#flushPendingSettings(rec);
             releaseExclusive();
             try {
                 await saveSessionMessages(this.#acpRoot, params.sessionId, serializeAgentMessages(rec.agent));
@@ -570,12 +735,69 @@ export class AcpAgent {
             }
         }
         if (consumeExitRequest(rec.agent)) {
-            await this.#disposeAllSessions();
+            await this.#disposeAll();
             setTimeout(() => process.exit(EXIT_REQUESTED_CODE), 25);
         }
         return { stopReason };
     }
-    async #dispatchModelStreamUpdate(sessionId, ev, rec) {
+    /**
+     * Surface the agent's todo list as an ACP `plan` update. Sends the complete
+     * list, as the client replaces the plan wholesale on each update. The
+     * in-progress entry uses its present-tense `activeForm` for a nicer live view.
+     */
+    #sendPlanUpdate(client, sessionId, rec) {
+        const { todos } = getTodoViewState(rec.agent);
+        return this.#sendUpdate(client, sessionId, {
+            sessionUpdate: "plan",
+            entries: todos.map((todo) => ({
+                content: todo.status === "in_progress" && todo.activeForm
+                    ? todo.activeForm
+                    : todo.content,
+                priority: todo.priority,
+                status: todo.status,
+            })),
+        });
+    }
+    /**
+     * Reflect an agent-driven mode change (e.g. `enter_plan_mode` /
+     * `exit_plan_mode`) to the client via `current_mode_update` and persist it.
+     */
+    async #syncCurrentMode(client, sessionId, rec) {
+        const modeId = resolveSessionMode(getModeState(rec.agent).mode);
+        await patchSessionMeta(this.#acpRoot, sessionId, { sessionMode: modeId });
+        await this.#sendUpdate(client, sessionId, {
+            sessionUpdate: "current_mode_update",
+            currentModeId: modeId,
+        });
+        // Config Options supersede modes; mirror the change for config-aware clients.
+        await this.#sendUpdate(client, sessionId, {
+            sessionUpdate: "config_option_update",
+            configOptions: buildSessionConfigOptions(rec.config, modeId),
+        });
+    }
+    /** Derive + persist a title from the first meaningful prompt echo. */
+    async #maybeDeriveTitle(client, sessionId, echo) {
+        const meta = await readSessionMeta(this.#acpRoot, sessionId);
+        const needsTitle = meta &&
+            (meta.title === undefined ||
+                meta.title === null ||
+                String(meta.title).trim() === "");
+        if (!needsTitle) {
+            return;
+        }
+        const title = deriveSessionTitleFromEcho(echo);
+        if (!title) {
+            return;
+        }
+        await patchSessionMeta(this.#acpRoot, sessionId, { title });
+        await this.#sendUpdate(client, sessionId, {
+            sessionUpdate: "session_info_update",
+            title,
+            updatedAt: new Date().toISOString(),
+        });
+    }
+    /** Translate a Strands model-stream event into ACP `session/update`s. */
+    async #dispatchModelStreamUpdate(client, sessionId, ev, rec) {
         const inner = ev.event;
         if (!isModelStreamEvent(inner)) {
             return;
@@ -587,16 +809,13 @@ export class AcpAgent {
                     rec.streamedToolCallIds.add(start.toolUseId);
                     rec.lastStreamToolUseId = start.toolUseId;
                     rec.streamingToolInputJson.set(start.toolUseId, "");
-                    await this.#connection.sessionUpdate({
-                        sessionId,
-                        update: {
-                            sessionUpdate: "tool_call",
-                            toolCallId: start.toolUseId,
-                            title: start.name,
-                            kind: inferToolKind(start.name),
-                            status: "pending",
-                            rawInput: {},
-                        },
+                    await this.#sendUpdate(client, sessionId, {
+                        sessionUpdate: "tool_call",
+                        toolCallId: start.toolUseId,
+                        title: start.name,
+                        kind: inferToolKind(start.name),
+                        status: "pending",
+                        rawInput: {},
                     });
                 }
                 return;
@@ -604,23 +823,17 @@ export class AcpAgent {
             case "modelContentBlockDeltaEvent": {
                 const { delta } = inner;
                 if (delta.type === "textDelta" && delta.text) {
-                    await this.#connection.sessionUpdate({
-                        sessionId,
-                        update: {
-                            sessionUpdate: "agent_message_chunk",
-                            content: { type: "text", text: delta.text },
-                        },
+                    await this.#sendUpdate(client, sessionId, {
+                        sessionUpdate: "agent_message_chunk",
+                        content: { type: "text", text: delta.text },
                     });
                     return;
                 }
                 if (delta.type === "reasoningContentDelta") {
                     if (delta.text) {
-                        await this.#connection.sessionUpdate({
-                            sessionId,
-                            update: {
-                                sessionUpdate: "agent_thought_chunk",
-                                content: { type: "text", text: delta.text },
-                            },
+                        await this.#sendUpdate(client, sessionId, {
+                            sessionUpdate: "agent_thought_chunk",
+                            content: { type: "text", text: delta.text },
                         });
                     }
                     return;
@@ -633,27 +846,21 @@ export class AcpAgent {
                     const prev = rec.streamingToolInputJson.get(toolUseId) ?? "";
                     const next = prev + delta.input;
                     rec.streamingToolInputJson.set(toolUseId, next);
-                    await this.#connection.sessionUpdate({
-                        sessionId,
-                        update: {
-                            sessionUpdate: "tool_call_update",
-                            toolCallId: toolUseId,
-                            rawInput: parseStreamingToolJson(next),
-                        },
+                    await this.#sendUpdate(client, sessionId, {
+                        sessionUpdate: "tool_call_update",
+                        toolCallId: toolUseId,
+                        rawInput: parseStreamingToolJson(next),
                     });
                     return;
                 }
                 if (delta.type === "citationsDelta") {
                     const n = delta.citations?.length ?? 0;
                     if (n > 0) {
-                        await this.#connection.sessionUpdate({
-                            sessionId,
-                            update: {
-                                sessionUpdate: "agent_thought_chunk",
-                                content: {
-                                    type: "text",
-                                    text: `[citations: ${n} reference(s)]\n`,
-                                },
+                        await this.#sendUpdate(client, sessionId, {
+                            sessionUpdate: "agent_thought_chunk",
+                            content: {
+                                type: "text",
+                                text: `[citations: ${n} reference(s)]\n`,
                             },
                         });
                     }
@@ -664,12 +871,9 @@ export class AcpAgent {
                 const replace = inner.outputRedaction?.replaceContent ??
                     inner.inputRedaction?.replaceContent;
                 if (replace) {
-                    await this.#connection.sessionUpdate({
-                        sessionId,
-                        update: {
-                            sessionUpdate: "agent_message_chunk",
-                            content: { type: "text", text: replace },
-                        },
+                    await this.#sendUpdate(client, sessionId, {
+                        sessionUpdate: "agent_message_chunk",
+                        content: { type: "text", text: replace },
                     });
                 }
                 return;
@@ -686,32 +890,216 @@ export class AcpAgent {
         const keys = [...rec.streamingToolInputJson.keys()];
         return keys.length === 1 ? keys[0] : undefined;
     }
-    async #disposeAllSessions() {
-        const ids = [...this.#sessions.keys()];
-        for (const id of ids) {
-            await this.#destroySession(id);
+    #sendUpdate(client, sessionId, update) {
+        return client.notify(methods.client.session.update, { sessionId, update });
+    }
+    #requireClient() {
+        if (!this.#client) {
+            throw RequestError.internalError({
+                message: "ACP client context is not available.",
+            });
         }
+        return this.#client;
     }
-    async #destroySession(sessionId) {
-        const rec = this.#sessions.get(sessionId);
-        if (!rec) {
+    async #bootstrapSession(sessionId, cwd, userId, mcpServers, mode, preferredModel) {
+        const client = this.#requireClient();
+        const sessionConfig = createSessionConfig();
+        if (preferredModel &&
+            preferredModel !== currentModelName(sessionConfig) &&
+            sessionConfig.llms.some((entry) => entry.name === preferredModel)) {
+            sessionConfig.update({
+                llms: sessionConfig.llms.map((entry) => ({
+                    ...entry,
+                    default: entry.name === preferredModel,
+                })),
+            });
+        }
+        const { config, agent, mcp: { manager }, } = await bootstrap("acp", {
+            userId,
+            sessionId,
+            mode,
+            createInterventions: () => [
+                createAcpToolApprovalIntervention(client, sessionId, () => this.#sessions.get(sessionId)?.streamedToolCallIds ??
+                    EMPTY_STREAMED_TOOL_CALL_IDS),
+            ],
+            acp: { mcpServers: mcpServers ?? [] },
+        }, false, sessionConfig);
+        this.#registerTextFsBackend(agent, client, sessionId);
+        this.#registerTerminalBackend(agent, client, sessionId);
+        return {
+            cwd,
+            agent,
+            config: config,
+            mcpDisconnect: () => manager.disconnect().catch(() => undefined),
+            turnAbort: null,
+            promptExclusive: Promise.resolve(),
+            streamedToolCallIds: new Set(),
+            streamingToolInputJson: new Map(),
+            lastStreamToolUseId: null,
+            pendingModeReapply: false,
+            pendingModelRebuild: false,
+        };
+    }
+    /**
+     * Route the built-in filesystem tools' text reads/writes through the client's
+     * `fs/*` methods when it advertised the capability during initialization.
+     */
+    #registerTextFsBackend(agent, client, sessionId) {
+        const caps = this.#clientFsCaps;
+        if (!caps || (!caps.readTextFile && !caps.writeTextFile)) {
             return;
         }
-        rec.turnAbort?.abort();
+        setTextFsBackend(agent, {
+            canRead: caps.readTextFile === true,
+            canWrite: caps.writeTextFile === true,
+            readTextFile: async (filePath, options) => {
+                const response = await client.request(methods.client.fs.readTextFile, {
+                    sessionId,
+                    path: filePath,
+                    ...(options?.line !== undefined ? { line: options.line } : {}),
+                    ...(options?.limit !== undefined ? { limit: options.limit } : {}),
+                });
+                return response.content;
+            },
+            writeTextFile: async (filePath, content) => {
+                await client.request(methods.client.fs.writeTextFile, {
+                    sessionId,
+                    path: filePath,
+                    content,
+                });
+            },
+        });
+    }
+    /**
+     * Route the built-in `shell` tool through the client's `terminal/*` methods
+     * when it advertised the `terminal` capability during initialization.
+     */
+    #registerTerminalBackend(agent, client, sessionId) {
+        if (!this.#clientTerminalCap) {
+            return;
+        }
+        setTerminalBackend(agent, {
+            run: (request) => this.#runClientTerminal(client, sessionId, request),
+        });
+    }
+    async #runClientTerminal(client, sessionId, request) {
+        const created = await client.request(methods.client.terminal.create, {
+            sessionId,
+            command: request.command,
+            args: request.args,
+            cwd: request.cwd,
+            ...(request.outputByteLimit !== undefined
+                ? { outputByteLimit: request.outputByteLimit }
+                : {}),
+        }, 
+        // Cascade `$/cancel_request` if the turn is cancelled before the terminal
+        // is created; once created we explicitly kill+release below instead.
+        { cancellationSignal: request.cancelSignal });
+        const terminalId = created.terminalId;
         try {
-            rec.agent.cancel();
+            // Embed the live terminal in the tool call so the client streams output.
+            if (request.toolUseId) {
+                await this.#sendUpdate(client, sessionId, {
+                    sessionUpdate: "tool_call_update",
+                    toolCallId: request.toolUseId,
+                    status: "in_progress",
+                    content: [{ type: "terminal", terminalId }],
+                });
+            }
+            const { exit, timedOut } = await this.#awaitTerminalExit(client, sessionId, terminalId, request);
+            const output = await client.request(methods.client.terminal.output, {
+                sessionId,
+                terminalId,
+            });
+            return {
+                output: output.output,
+                truncated: output.truncated,
+                exitCode: exit?.exitCode ?? output.exitStatus?.exitCode ?? null,
+                signal: exit?.signal ?? output.exitStatus?.signal ?? null,
+                timedOut,
+            };
         }
-        catch {
-            /* ignore */
+        finally {
+            await client
+                .request(methods.client.terminal.release, { sessionId, terminalId })
+                .catch(() => undefined);
         }
-        await flushAgentMemory(rec.agent).catch(() => { });
-        await rec.mcpDisconnect();
-        this.#sessions.delete(sessionId);
     }
+    /**
+     * Wait for the command to exit, killing it if the timeout elapses or the turn
+     * is cancelled (spec: "Building a Timeout").
+     */
+    async #awaitTerminalExit(client, sessionId, terminalId, request) {
+        const waitForExit = client.request(methods.client.terminal.waitForExit, {
+            sessionId,
+            terminalId,
+        });
+        // Both branches are handled so a late settle never becomes unhandled.
+        const exitRace = waitForExit.then((value) => ({ kind: "exit", value }), () => ({ kind: "exit", value: null }));
+        let timer;
+        const timeoutRace = new Promise((resolve) => {
+            timer = setTimeout(() => resolve({ kind: "timeout" }), request.timeoutMs);
+        });
+        const signal = request.cancelSignal;
+        let onAbort;
+        const cancelRace = new Promise((resolve) => {
+            if (!signal) {
+                return;
+            }
+            if (signal.aborted) {
+                resolve({ kind: "cancel" });
+                return;
+            }
+            onAbort = () => resolve({ kind: "cancel" });
+            signal.addEventListener("abort", onAbort, { once: true });
+        });
+        try {
+            const winner = await Promise.race([exitRace, timeoutRace, cancelRace]);
+            if (winner.kind === "exit") {
+                return { exit: winner.value, timedOut: false };
+            }
+            await client
+                .request(methods.client.terminal.kill, { sessionId, terminalId })
+                .catch(() => undefined);
+            return { exit: null, timedOut: winner.kind === "timeout" };
+        }
+        finally {
+            if (timer) {
+                clearTimeout(timer);
+            }
+            if (signal && onAbort) {
+                signal.removeEventListener("abort", onAbort);
+            }
+        }
+    }
+    async #disposeAll() {
+        const records = [...this.#sessions.values()];
+        this.#sessions.clear();
+        for (const record of records) {
+            record.turnAbort?.abort();
+            await record.mcpDisconnect();
+        }
+    }
+}
+/** Build the ACP agent app and register the handlers implemented so far. */
+export function createAcpApp(agent) {
+    return acpAgent({ name: "hooman" })
+        .onConnect((connection) => agent.onConnect(connection))
+        .onRequest(methods.agent.initialize, (ctx) => agent.initialize(ctx.params))
+        .onRequest(methods.agent.session.new, (ctx) => agent.newSession(ctx.params))
+        .onRequest(methods.agent.session.load, (ctx) => agent.loadSession(ctx.params, ctx.client))
+        .onRequest(methods.agent.session.list, (ctx) => agent.listSessions(ctx.params))
+        .onRequest(methods.agent.session.delete, (ctx) => agent.deleteSession(ctx.params))
+        .onRequest(methods.agent.session.setMode, (ctx) => agent.setSessionMode(ctx.params))
+        .onRequest(methods.agent.session.setConfigOption, (ctx) => agent.setSessionConfigOption(ctx.params))
+        .onRequest(methods.agent.session.prompt, (ctx) => agent.prompt(ctx.params))
+        .onNotification(methods.agent.session.cancel, (ctx) => agent.cancel(ctx.params));
 }
+/** Run Hooman as an ACP agent over stdio. */
 export async function runAcpStdio() {
+    const identity = await readAgentIdentity();
     const stream = ndJsonStream(Writable.toWeb(stdout), Readable.toWeb(stdin));
-    const connection = new AgentSideConnection((conn) => new AcpAgent(conn), stream);
+    const connection = createAcpApp(new HoomanAcpAgent(identity)).connect(stream);
     await connection.closed;
 }
 //# sourceMappingURL=acp-agent.js.map