claude-code-acp-ts 0.24.3 → 0.37.0

package/dist/acp-agent.js

@@ -1,12 +1,11 @@
 import { AgentSideConnection, ndJsonStream, RequestError, } from "@agentclientprotocol/sdk";
-import { getSessionMessages, listSessions, query, } from "@anthropic-ai/claude-agent-sdk";
+import { deleteSession, getSessionMessages, listSessions, query, } from "@anthropic-ai/claude-agent-sdk";
 import { randomUUID } from "node:crypto";
-import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import packageJson from "../package.json" with { type: "json" };
 import { SettingsManager } from "./settings.js";
-import { createPostToolUseHook, planEntries, registerHookCallback, toolInfoFromToolUse, toolUpdateFromEditToolResponse, toolUpdateFromToolResult, } from "./tools.js";
+import { applyTaskCreate, applyTaskUpdate, createPostToolUseHook, createTaskHook, parseTaskCreateOutput, planEntries, registerHookCallback, taskStateToPlanEntries, toolInfoFromToolUse, toolUpdateFromDiffToolResponse, toolUpdateFromToolResult, } from "./tools.js";
 import { nodeToWebReadable, nodeToWebWritable, Pushable, unreachable } from "./utils.js";
 export const CLAUDE_CONFIG_DIR = process.env.CLAUDE_CONFIG_DIR ?? path.join(os.homedir(), ".claude");
 const MAX_TITLE_LENGTH = 256;
@@ -21,13 +20,63 @@ function sanitizeTitle(text) {
     }
     return sanitized.slice(0, MAX_TITLE_LENGTH - 1) + "…";
 }
-function isStaticBinary() {
-    return process.env.CLAUDE_AGENT_ACP_IS_SINGLE_FILE_BUN !== undefined;
+const ZERO_USAGE = Object.freeze({
+    input_tokens: 0,
+    output_tokens: 0,
+    cache_read_input_tokens: 0,
+    cache_creation_input_tokens: 0,
+});
+const DEFAULT_CONTEXT_WINDOW = 200000;
+/** Compute a stable fingerprint of the session-defining params so we can
+ *  detect when a loadSession/resumeSession call requires tearing down and
+ *  recreating the underlying Query process.  MCP servers are sorted by name
+ *  so that ordering differences don't trigger unnecessary recreations. */
+function computeSessionFingerprint(params) {
+    const servers = [...(params.mcpServers ?? [])].sort((a, b) => a.name.localeCompare(b.name));
+    return JSON.stringify({ cwd: params.cwd, mcpServers: servers });
 }
 export async function claudeCliPath() {
-    return isStaticBinary()
-        ? (await import("@anthropic-ai/claude-agent-sdk/embed")).default
-        : import.meta.resolve("@anthropic-ai/claude-agent-sdk").replace("sdk.mjs", "cli.js");
+    if (process.env.CLAUDE_CODE_EXECUTABLE) {
+        return process.env.CLAUDE_CODE_EXECUTABLE;
+    }
+    // The SDK's CLI is a native binary shipped as a platform-specific optional
+    // dependency of @anthropic-ai/claude-agent-sdk. Resolve via a require bound
+    // to the SDK so nested installs are found even when npm doesn't hoist.
+    const { createRequire } = await import("node:module");
+    const req = createRequire(import.meta.resolve("@anthropic-ai/claude-agent-sdk"));
+    const ext = process.platform === "win32" ? ".exe" : "";
+    // On linux, both glibc and musl variants may be installed side-by-side
+    // (e.g. bunx hydrates every optional dep), so picking one by trial is
+    // unreliable: the wrong binary segfaults at runtime instead of failing to
+    // spawn. Detect the runtime libc and prefer the matching variant, falling
+    // back to the other only if the preferred one isn't installed.
+    const candidates = process.platform === "linux"
+        ? isMuslLibc()
+            ? [
+                `@anthropic-ai/claude-agent-sdk-linux-${process.arch}-musl/claude${ext}`,
+                `@anthropic-ai/claude-agent-sdk-linux-${process.arch}/claude${ext}`,
+            ]
+            : [
+                `@anthropic-ai/claude-agent-sdk-linux-${process.arch}/claude${ext}`,
+                `@anthropic-ai/claude-agent-sdk-linux-${process.arch}-musl/claude${ext}`,
+            ]
+        : [`@anthropic-ai/claude-agent-sdk-${process.platform}-${process.arch}/claude${ext}`];
+    for (const candidate of candidates) {
+        try {
+            return req.resolve(candidate);
+        }
+        catch {
+            // try next candidate
+        }
+    }
+    throw new Error(`Claude native binary not found for ${process.platform}-${process.arch}. ` +
+        `Reinstall @anthropic-ai/claude-agent-sdk without --omit=optional, or set CLAUDE_CODE_EXECUTABLE.`);
+}
+function isMuslLibc() {
+    // process.report.getReport().header.glibcVersionRuntime is populated when
+    // Node is dynamically linked against glibc, and absent on musl.
+    const report = process.report?.getReport();
+    return !report?.header?.glibcVersionRuntime;
 }
 function shouldHideClaudeAuth() {
     return process.argv.includes("--hide-claude-auth");
@@ -38,7 +87,54 @@ const ALLOW_BYPASS = !IS_ROOT || !!process.env.IS_SANDBOX;
 // Slash commands that the SDK handles locally without replaying the user
 // message and without invoking the model.
 const LOCAL_ONLY_COMMANDS = new Set(["/context", "/heapdump", "/extra-usage"]);
+// The Claude SDK persists local slash command invocations (e.g. `/model`) and
+// their output as user messages in the session transcript, wrapping the
+// payload in these XML-like markers that the CLI uses for its own display.
+// The live prompt loop drops them; replay must strip them too or they leak
+// into the UI on session/load.
+const LOCAL_COMMAND_TAG_PATTERN = /<(command-name|command-message|command-args|local-command-stdout|local-command-stderr)>[\s\S]*?<\/\1>/g;
+function stripMarkerTags(text) {
+    return text.replace(LOCAL_COMMAND_TAG_PATTERN, "");
+}
+/**
+ * Return user-message content with local-command marker tags removed, or
+ * `null` if nothing meaningful remains (caller should skip the message).
+ * Preserves real prose that's mixed in alongside the markers — e.g. a
+ * message like `<command-name>…</command-name>hi` becomes `hi`.
+ */
+export function stripLocalCommandMetadata(content) {
+    if (typeof content === "string") {
+        const stripped = stripMarkerTags(content);
+        return stripped.trim() === "" ? null : stripped;
+    }
+    if (!Array.isArray(content))
+        return content;
+    const kept = [];
+    for (const block of content) {
+        if (block &&
+            typeof block === "object" &&
+            "type" in block &&
+            block.type === "text" &&
+            "text" in block &&
+            typeof block.text === "string") {
+            const stripped = stripMarkerTags(block.text);
+            if (stripped.trim() === "")
+                continue;
+            kept.push({ ...block, text: stripped });
+        }
+        else {
+            kept.push(block);
+        }
+    }
+    if (kept.length === 0)
+        return null;
+    return kept;
+}
+export function isLocalCommandMetadata(content) {
+    return stripLocalCommandMetadata(content) === null;
+}
 const PERMISSION_MODE_ALIASES = {
+    auto: "auto",
     default: "default",
     acceptedits: "acceptEdits",
     dontask: "dontAsk",
@@ -46,26 +142,64 @@ const PERMISSION_MODE_ALIASES = {
     bypasspermissions: "bypassPermissions",
     bypass: "bypassPermissions",
 };
-export function resolvePermissionMode(defaultMode) {
+export function resolvePermissionMode(defaultMode, logger = console) {
     if (defaultMode === undefined) {
         return "default";
     }
     if (typeof defaultMode !== "string") {
-        throw new Error("Invalid permissions.defaultMode: expected a string.");
+        logger.error("Ignoring permissions.defaultMode from settings: expected a string.");
+        return "default";
     }
     const normalized = defaultMode.trim().toLowerCase();
     if (normalized === "") {
-        throw new Error("Invalid permissions.defaultMode: expected a non-empty string.");
+        logger.error("Ignoring permissions.defaultMode from settings: expected a non-empty string.");
+        return "default";
     }
     const mapped = PERMISSION_MODE_ALIASES[normalized];
     if (!mapped) {
-        throw new Error(`Invalid permissions.defaultMode: ${defaultMode}.`);
+        logger.error(`Ignoring permissions.defaultMode from settings: unknown value '${defaultMode}'.`);
+        return "default";
     }
     if (mapped === "bypassPermissions" && !ALLOW_BYPASS) {
-        throw new Error("Invalid permissions.defaultMode: bypassPermissions is not available when running as root.");
+        logger.error("Ignoring permissions.defaultMode from settings: bypassPermissions is not available when running as root.");
+        return "default";
     }
     return mapped;
 }
+/**
+ * Builds the label for the "Always Allow" permission option so the user can see
+ * the exact scope they are committing to. Uses the SDK-provided suggestions
+ * when available (e.g. `Bash(npm test:*)`) and falls back to naming the whole
+ * tool so "Always Allow" is never a blank check without disclosure.
+ */
+export function describeAlwaysAllow(suggestions, toolName) {
+    if (!suggestions || suggestions.length === 0) {
+        return `Always Allow all ${toolName}`;
+    }
+    const ruleLabels = [];
+    const directories = [];
+    for (const update of suggestions) {
+        if (update.type === "addRules" && update.behavior === "allow") {
+            for (const rule of update.rules) {
+                ruleLabels.push(rule.ruleContent ? `${rule.toolName}(${rule.ruleContent})` : `all ${rule.toolName}`);
+            }
+        }
+        else if (update.type === "addDirectories") {
+            directories.push(...update.directories);
+        }
+    }
+    const parts = [];
+    if (ruleLabels.length > 0) {
+        parts.push(ruleLabels.join(", "));
+    }
+    if (directories.length > 0) {
+        parts.push(`access to ${directories.join(", ")}`);
+    }
+    if (parts.length === 0) {
+        return `Always Allow all ${toolName}`;
+    }
+    return `Always Allow ${parts.join(" and ")}`;
+}
 // Implement the ACP Agent interface
 export class ClaudeAcpAgent {
     constructor(client, logger) {
@@ -90,24 +224,87 @@ export class ClaudeAcpAgent {
                 },
             },
         };
-        const terminalAuthMethod = {
-            description: "Run `claude /login` in the terminal",
-            name: "Log in with Claude",
-            id: "claude-login",
-            type: "terminal",
-            args: ["--cli"],
+        const gatewayBedrockAuthMethod = {
+            id: "gateway-bedrock",
+            name: "Custom model gateway",
+            description: "Use a custom gateway to authenticate and access models",
+            _meta: {
+                gateway: {
+                    protocol: "bedrock",
+                },
+            },
         };
         const supportsTerminalAuth = request.clientCapabilities?.auth?.terminal === true;
-        // If client supports terminal-auth capability, use that instead.
         const supportsMetaTerminalAuth = request.clientCapabilities?._meta?.["terminal-auth"] === true;
-        if (supportsMetaTerminalAuth) {
-            terminalAuthMethod._meta = {
-                "terminal-auth": {
-                    command: process.execPath,
-                    args: [...process.argv.slice(1), "--cli"],
-                    label: "Claude Login",
-                },
+        // Detect remote environments where the OAuth browser redirect to localhost
+        // won't work. This matches the SDK's internal isRemote check. In these cases,
+        // the `auth login` subcommand would fall back to a device-code-like manual
+        // flow, which doesn't work well over ACP, so we offer the TUI login instead.
+        const isRemote = !!(process.env.NO_BROWSER ||
+            process.env.SSH_CONNECTION ||
+            process.env.SSH_CLIENT ||
+            process.env.SSH_TTY ||
+            process.env.CLAUDE_CODE_REMOTE);
+        const terminalAuthMethods = [];
+        if (isRemote) {
+            const remoteLoginMethod = {
+                description: "Run `claude /login` in the terminal",
+                name: "Log in with Claude",
+                id: "claude-login",
+                type: "terminal",
+                args: ["--cli"],
             };
+            if (supportsMetaTerminalAuth) {
+                remoteLoginMethod._meta = {
+                    "terminal-auth": {
+                        command: process.execPath,
+                        args: [...process.argv.slice(1), "--cli"],
+                        label: "Claude Login",
+                    },
+                };
+            }
+            if (!shouldHideClaudeAuth() && (supportsTerminalAuth || supportsMetaTerminalAuth)) {
+                terminalAuthMethods.push(remoteLoginMethod);
+            }
+        }
+        else {
+            const claudeLoginMethod = {
+                description: "Use Claude subscription ",
+                name: "Claude Subscription",
+                id: "claude-ai-login",
+                type: "terminal",
+                args: ["--cli", "auth", "login", "--claudeai"],
+            };
+            const consoleLoginMethod = {
+                description: "Use Anthropic Console (API usage billing)",
+                name: "Anthropic Console",
+                id: "console-login",
+                type: "terminal",
+                args: ["--cli", "auth", "login", "--console"],
+            };
+            if (supportsMetaTerminalAuth) {
+                const baseArgs = process.argv.slice(1);
+                claudeLoginMethod._meta = {
+                    "terminal-auth": {
+                        command: process.execPath,
+                        args: [...baseArgs, "--cli", "auth", "login", "--claudeai"],
+                        label: "Claude Login",
+                    },
+                };
+                consoleLoginMethod._meta = {
+                    "terminal-auth": {
+                        command: process.execPath,
+                        args: [...baseArgs, "--cli", "auth", "login", "--console"],
+                        label: "Anthropic Console Login",
+                    },
+                };
+            }
+            if (!shouldHideClaudeAuth() && (supportsTerminalAuth || supportsMetaTerminalAuth)) {
+                terminalAuthMethods.push(claudeLoginMethod);
+            }
+            if (supportsTerminalAuth || supportsMetaTerminalAuth) {
+                terminalAuthMethods.push(consoleLoginMethod);
+            }
         }
         return {
             protocolVersion: 1,
@@ -127,10 +324,12 @@ export class ClaudeAcpAgent {
                 },
                 loadSession: true,
                 sessionCapabilities: {
+                    additionalDirectories: {},
+                    close: {},
+                    delete: {},
                     fork: {},
                     list: {},
                     resume: {},
-                    close: {},
                 },
             },
             agentInfo: {
@@ -139,19 +338,12 @@ export class ClaudeAcpAgent {
                 version: packageJson.version,
             },
             authMethods: [
-                ...(!shouldHideClaudeAuth() && (supportsTerminalAuth || supportsMetaTerminalAuth)
-                    ? [terminalAuthMethod]
-                    : []),
-                ...(supportsGatewayAuth ? [gatewayAuthMethod] : []),
+                ...terminalAuthMethods,
+                ...(supportsGatewayAuth ? [gatewayAuthMethod, gatewayBedrockAuthMethod] : []),
             ],
         };
     }
     async newSession(params) {
-        if (!this.gatewayAuthMeta &&
-            fs.existsSync(path.resolve(os.homedir(), ".claude.json.backup")) &&
-            !fs.existsSync(path.resolve(os.homedir(), ".claude.json"))) {
-            throw RequestError.authRequired();
-        }
         const response = await this.createSession(params, {
             // Revisit these meta values once we support resume
             resume: params._meta?.claudeCode?.options?.resume,
@@ -166,6 +358,7 @@ export class ClaudeAcpAgent {
         const response = await this.createSession({
             cwd: params.cwd,
             mcpServers: params.mcpServers ?? [],
+            additionalDirectories: params.additionalDirectories,
             _meta: params._meta,
         }, {
             resume: params.sessionId,
@@ -177,7 +370,7 @@ export class ClaudeAcpAgent {
         }, 0);
         return response;
     }
-    async unstable_resumeSession(params) {
+    async resumeSession(params) {
         const result = await this.getOrCreateSession(params);
         // Needs to happen after we return the session
         setTimeout(() => {
@@ -212,8 +405,8 @@ export class ClaudeAcpAgent {
         };
     }
     async authenticate(_params) {
-        if (_params.methodId === "gateway") {
-            this.gatewayAuthMeta = _params._meta;
+        if (_params.methodId === "gateway" || _params.methodId === "gateway-bedrock") {
+            this.gatewayAuthRequest = _params;
             return;
         }
         throw new Error("Method not implemented.");
@@ -231,8 +424,15 @@ export class ClaudeAcpAgent {
             cachedWriteTokens: 0,
         };
         let lastAssistantTotalUsage = null;
+        let lastAssistantUsage = null;
         let lastAssistantModel = null;
-        let lastContextWindowSize = 200000;
+        // When the Claude SDK classifies a turn as failed (e.g. rate limit, auth
+        // problem, billing), it sets a categorical `error` field on the
+        // `SDKAssistantMessage` that precedes the final `result` message. We
+        // capture it here so the subsequent `RequestError.internalError` can
+        // forward it to clients as structured `data`, sparing them from
+        // pattern-matching on the human-readable message text.
+        let lastAssistantError;
         const userMessage = promptToClaude(params);
         const promptUuid = randomUUID();
         userMessage.uuid = promptUuid;
@@ -256,6 +456,7 @@ export class ClaudeAcpAgent {
         }
         session.promptRunning = true;
         let handedOff = false;
+        let errored = false;
         let stopReason = "end_turn";
         try {
             while (true) {
@@ -266,6 +467,13 @@ export class ClaudeAcpAgent {
                     }
                     break;
                 }
+                if (session.emitRawSDKMessages &&
+                    shouldEmitRawMessage(session.emitRawSDKMessages, message)) {
+                    await this.client.extNotification("_claude/sdkMessage", {
+                        sessionId: params.sessionId,
+                        message: message,
+                    });
+                }
                 switch (message.type) {
                     case "system":
                         switch (message.subtype) {
@@ -296,12 +504,13 @@ export class ClaudeAcpAgent {
                                 // "944k/1m" right after the user sees "Compacting completed",
                                 // which is confusing and wrong.
                                 lastAssistantTotalUsage = 0;
+                                lastAssistantUsage = null;
                                 await this.client.sessionUpdate({
                                     sessionId: message.session_id,
                                     update: {
                                         sessionUpdate: "usage_update",
                                         used: 0,
-                                        size: lastContextWindowSize,
+                                        size: session.contextWindowSize,
                                     },
                                 });
                                 await this.client.sessionUpdate({
@@ -325,10 +534,50 @@ export class ClaudeAcpAgent {
                             }
                             case "session_state_changed": {
                                 if (message.state === "idle") {
+                                    if (session.cancelled) {
+                                        stopReason = "cancelled";
+                                    }
                                     return { stopReason, usage: sessionUsage(session) };
                                 }
                                 break;
                             }
+                            case "memory_recall": {
+                                const isSynthesis = message.mode === "synthesize";
+                                const locations = isSynthesis
+                                    ? []
+                                    : message.memories.map((m) => ({ path: m.path }));
+                                const content = isSynthesis
+                                    ? message.memories
+                                        .filter((m) => typeof m.content === "string")
+                                        .map((m) => ({
+                                        type: "content",
+                                        content: { type: "text", text: m.content },
+                                    }))
+                                    : [];
+                                const count = message.memories.length;
+                                const title = isSynthesis
+                                    ? "Recalled synthesized memory"
+                                    : `Recalled ${count} ${count === 1 ? "memory" : "memories"}`;
+                                await this.client.sessionUpdate({
+                                    sessionId: message.session_id,
+                                    update: {
+                                        sessionUpdate: "tool_call",
+                                        toolCallId: message.uuid,
+                                        title,
+                                        kind: "read",
+                                        status: "completed",
+                                        ...(locations.length > 0 && { locations }),
+                                        ...(content.length > 0 && { content }),
+                                        _meta: {
+                                            claudeCode: {
+                                                toolName: "memory_recall",
+                                                toolResponse: { mode: message.mode },
+                                            },
+                                        },
+                                    },
+                                });
+                                break;
+                            }
                             case "hook_started":
                             case "hook_progress":
                             case "hook_response":
@@ -336,8 +585,13 @@ export class ClaudeAcpAgent {
                             case "task_started":
                             case "task_notification":
                             case "task_progress":
+                            case "task_updated":
                             case "elicitation_complete":
+                            case "plugin_install":
+                            case "notification":
                             case "api_retry":
+                            case "mirror_error":
+                            case "permission_denied":
                                 // Todo: process via status api: https://docs.claude.com/en/docs/claude-code/hooks#hook-output
                                 break;
                             default:
@@ -354,8 +608,18 @@ export class ClaudeAcpAgent {
                         const matchingModelUsage = lastAssistantModel
                             ? getMatchingModelUsage(message.modelUsage, lastAssistantModel)
                             : null;
-                        const contextWindowSize = matchingModelUsage?.contextWindow ?? 200000;
-                        lastContextWindowSize = contextWindowSize;
+                        // Only overwrite when we have an authoritative value — a miss
+                        // (e.g. a turn with no top-level assistant message) would
+                        // otherwise discard the window learned on a prior turn and
+                        // leave the next prompt's mid-stream updates reporting 200k.
+                        if (matchingModelUsage) {
+                            session.contextWindowSize = matchingModelUsage.contextWindow;
+                        }
+                        // Task-notification followups are autonomous work triggered by a
+                        // task-notification system message, not by the user's prompt.
+                        // They should not influence the user-turn lifecycle (stop reason,
+                        // slash-command output forwarding) but their cost is real.
+                        const isTaskNotification = message.origin?.kind === "task-notification";
                         // Send usage_update notification
                         if (lastAssistantTotalUsage !== null) {
                             await this.client.sessionUpdate({
@@ -363,16 +627,21 @@ export class ClaudeAcpAgent {
                                 update: {
                                     sessionUpdate: "usage_update",
                                     used: lastAssistantTotalUsage,
-                                    size: contextWindowSize,
+                                    size: session.contextWindowSize,
                                     cost: {
                                         amount: message.total_cost_usd,
                                         currency: "USD",
                                     },
+                                    ...(message.origin && {
+                                        _meta: { "_claude/origin": message.origin },
+                                    }),
                                 },
                             });
                         }
                         if (session.cancelled) {
-                            stopReason = "cancelled";
+                            if (!isTaskNotification) {
+                                stopReason = "cancelled";
+                            }
                             break;
                         }
                         switch (message.subtype) {
@@ -381,15 +650,19 @@ export class ClaudeAcpAgent {
                                     throw RequestError.authRequired();
                                 }
                                 if (message.stop_reason === "max_tokens") {
-                                    stopReason = "max_tokens";
+                                    if (!isTaskNotification) {
+                                        stopReason = "max_tokens";
+                                    }
                                     break;
                                 }
                                 if (message.is_error) {
-                                    throw RequestError.internalError(undefined, message.result);
+                                    throw RequestError.internalError(errorKindData(lastAssistantError), message.result);
                                 }
                                 // For local-only commands (no model invocation), the result
                                 // text is the command output — forward it to the client.
-                                if (isLocalOnlyCommand) {
+                                // Task-notification followups never originate from a user
+                                // slash command, so skip the forwarding for them.
+                                if (isLocalOnlyCommand && !isTaskNotification) {
                                     for (const notification of toAcpNotifications(message.result, "assistant", params.sessionId, this.toolUseCache, this.client, this.logger)) {
                                         await this.client.sessionUpdate(notification);
                                     }
@@ -398,22 +671,28 @@ export class ClaudeAcpAgent {
                             }
                             case "error_during_execution": {
                                 if (message.stop_reason === "max_tokens") {
-                                    stopReason = "max_tokens";
+                                    if (!isTaskNotification) {
+                                        stopReason = "max_tokens";
+                                    }
                                     break;
                                 }
                                 if (message.is_error) {
-                                    throw RequestError.internalError(undefined, message.errors.join(", ") || message.subtype);
+                                    throw RequestError.internalError(errorKindData(lastAssistantError), message.errors.join(", ") || message.subtype);
+                                }
+                                if (!isTaskNotification) {
+                                    stopReason = "end_turn";
                                 }
-                                stopReason = "end_turn";
                                 break;
                             }
                             case "error_max_budget_usd":
                             case "error_max_turns":
                             case "error_max_structured_output_retries":
                                 if (message.is_error) {
-                                    throw RequestError.internalError(undefined, message.errors.join(", ") || message.subtype);
+                                    throw RequestError.internalError(errorKindData(lastAssistantError), message.errors.join(", ") || message.subtype);
+                                }
+                                if (!isTaskNotification) {
+                                    stopReason = "max_turn_requests";
                                 }
-                                stopReason = "max_turn_requests";
                                 break;
                             default:
                                 unreachable(message, this.logger);
@@ -422,9 +701,57 @@ export class ClaudeAcpAgent {
                         break;
                     }
                     case "stream_event": {
+                        if (message.parent_tool_use_id === null &&
+                            (message.event.type === "message_start" || message.event.type === "message_delta")) {
+                            if (message.event.type === "message_start") {
+                                lastAssistantUsage = snapshotFromUsage(message.event.message.usage);
+                                const model = message.event.message.model;
+                                if (model && model !== "<synthetic>") {
+                                    lastAssistantModel = model;
+                                    // Only upgrade from the default — once a `result` has given
+                                    // us an authoritative window, trust it over the heuristic.
+                                    // Model switches invalidate the cached window via
+                                    // `syncSessionConfigState`, which resets us back to the
+                                    // default so this branch runs again for the new model.
+                                    if (session.contextWindowSize === DEFAULT_CONTEXT_WINDOW) {
+                                        const inferred = inferContextWindowFromModel(model);
+                                        if (inferred !== null) {
+                                            session.contextWindowSize = inferred;
+                                        }
+                                    }
+                                }
+                            }
+                            else {
+                                const usage = message.event.usage;
+                                const prev = lastAssistantUsage ?? ZERO_USAGE;
+                                // Per Anthropic API, message_delta usage fields are *cumulative*;
+                                // nullable fields (input_tokens and the cache fields) fall back
+                                // to the prior snapshot when the server omits them from this
+                                // delta. Only output_tokens is guaranteed non-null.
+                                lastAssistantUsage = {
+                                    input_tokens: usage.input_tokens ?? prev.input_tokens,
+                                    output_tokens: usage.output_tokens,
+                                    cache_read_input_tokens: usage.cache_read_input_tokens ?? prev.cache_read_input_tokens,
+                                    cache_creation_input_tokens: usage.cache_creation_input_tokens ?? prev.cache_creation_input_tokens,
+                                };
+                            }
+                            const nextUsage = totalTokens(lastAssistantUsage);
+                            if (nextUsage !== lastAssistantTotalUsage) {
+                                lastAssistantTotalUsage = nextUsage;
+                                await this.client.sessionUpdate({
+                                    sessionId: params.sessionId,
+                                    update: {
+                                        sessionUpdate: "usage_update",
+                                        used: nextUsage,
+                                        size: session.contextWindowSize,
+                                    },
+                                });
+                            }
+                        }
                         for (const notification of streamEventToAcpNotifications(message, params.sessionId, this.toolUseCache, this.client, this.logger, {
                             clientCapabilities: this.clientCapabilities,
                             cwd: session.cwd,
+                            taskState: session.taskState,
                         })) {
                             await this.client.sessionUpdate(notification);
                         }
@@ -454,33 +781,41 @@ export class ClaudeAcpAgent {
                                 break;
                             }
                         }
-                        // Store latest assistant usage (excluding subagents)
-                        // Sum all token types as a proxy for post-turn context occupancy:
-                        // current turn's output will become next turn's input.
-                        // Note: per the Anthropic API, input_tokens excludes cache tokens —
-                        // cache_read and cache_creation are reported separately, so summing
-                        // all four fields is not double-counting.
-                        if (message.message.usage && message.parent_tool_use_id === null) {
-                            const messageWithUsage = message.message;
-                            lastAssistantTotalUsage =
-                                messageWithUsage.usage.input_tokens +
-                                    messageWithUsage.usage.output_tokens +
-                                    messageWithUsage.usage.cache_read_input_tokens +
-                                    messageWithUsage.usage.cache_creation_input_tokens;
-                        }
-                        // Track the current top-level model for context window size lookup
-                        // (exclude subagent messages to stay in sync with lastAssistantTotalUsage)
-                        if (message.type === "assistant" &&
-                            message.parent_tool_use_id === null &&
-                            message.message.model &&
-                            message.message.model !== "<synthetic>") {
-                            lastAssistantModel = message.message.model;
+                        // Snapshot the latest top-level assistant usage and model so the
+                        // next `result` can emit a usage_update tied to the right context
+                        // window. Subagent messages are excluded to keep the snapshot
+                        // aligned with what the user's current selection is producing.
+                        if (message.type === "assistant" && message.parent_tool_use_id === null) {
+                            lastAssistantUsage = snapshotFromUsage(message.message.usage);
+                            lastAssistantTotalUsage = totalTokens(lastAssistantUsage);
+                            if (message.message.model && message.message.model !== "<synthetic>") {
+                                lastAssistantModel = message.message.model;
+                            }
+                            if (message.error) {
+                                lastAssistantError = message.error;
+                            }
                         }
-                        // Slash commands like /compact can generate invalid output... doesn't match
-                        // their own docs: https://docs.anthropic.com/en/docs/claude-code/sdk/sdk-slash-commands#%2Fcompact-compact-conversation-history
+                        // Strip <command-*>/<local-command-stdout> markers and render any
+                        // remaining prose. Skill bodies and built-in slash commands (e.g.
+                        // /usage, /status, /model) arrive wrapped in these tags; pure-marker
+                        // payloads (e.g. /compact's malformed output) strip to null and are
+                        // skipped. Mirrors the replay path at replaySessionHistory.
                         if (typeof message.message.content === "string" &&
                             message.message.content.includes("<local-command-stdout>")) {
-                            this.logger.log(message.message.content);
+                            const stripped = stripLocalCommandMetadata(message.message.content);
+                            if (typeof stripped === "string") {
+                                for (const notification of toAcpNotifications(stripped, message.message.role, params.sessionId, this.toolUseCache, this.client, this.logger, {
+                                    clientCapabilities: this.clientCapabilities,
+                                    parentToolUseId: message.parent_tool_use_id,
+                                    cwd: session.cwd,
+                                    taskState: session.taskState,
+                                })) {
+                                    await this.client.sessionUpdate(notification);
+                                }
+                            }
+                            else {
+                                this.logger.log(message.message.content);
+                            }
                             break;
                         }
                         if (typeof message.message.content === "string" &&
@@ -512,6 +847,7 @@ export class ClaudeAcpAgent {
                             clientCapabilities: this.clientCapabilities,
                             parentToolUseId: message.parent_tool_use_id,
                             cwd: session.cwd,
+                            taskState: session.taskState,
                         })) {
                             await this.client.sessionUpdate(notification);
                         }
@@ -531,6 +867,30 @@ export class ClaudeAcpAgent {
             throw new Error("Session did not end in result");
         }
         catch (error) {
+            errored = true;
+            // A failed turn typically leaves a trailing `session_state_changed: idle`
+            // (and possibly more) in the query iterator. If we don't drain it here,
+            // the next prompt's first `query.next()` consumes that stale idle and
+            // short-circuits to end_turn with zero usage
+            // Bounded so a misbehaving SDK can't hang the next prompt indefinitely.
+            try {
+                await session.query.interrupt();
+                const MAX_DRAIN = 100;
+                for (let i = 0; i < MAX_DRAIN; i++) {
+                    const { value: m, done } = await session.query.next();
+                    if (done || !m)
+                        break;
+                    if (m.type === "system" && m.subtype === "session_state_changed" && m.state === "idle") {
+                        break;
+                    }
+                    if (i === MAX_DRAIN - 1) {
+                        this.logger.error(`Session ${params.sessionId}: drained ${MAX_DRAIN} messages after error without observing idle`);
+                    }
+                }
+            }
+            catch (drainErr) {
+                this.logger.error(`Session ${params.sessionId}: failed to drain query after prompt error:`, drainErr);
+            }
             if (error instanceof RequestError || !(error instanceof Error)) {
                 throw error;
             }
@@ -551,10 +911,20 @@ export class ClaudeAcpAgent {
         finally {
             if (!handedOff) {
                 session.promptRunning = false;
-                // This usually should not happen, but in case the loop finishes
-                // without claude sending all message replays, we resolve the
-                // next pending prompt call to ensure no prompts get stuck.
-                if (session.pendingMessages.size > 0) {
+                if (errored) {
+                    // The query stream was just drained — handing pending prompts off
+                    // onto it would let them race with the recovery. Cancel them so
+                    // each waiting prompt() returns stopReason: "cancelled" and the
+                    // client can decide whether to retry.
+                    for (const pending of session.pendingMessages.values()) {
+                        pending.resolve(true);
+                    }
+                    session.pendingMessages.clear();
+                }
+                else if (session.pendingMessages.size > 0) {
+                    // This usually should not happen, but in case the loop finishes
+                    // without claude sending all message replays, we resolve the
+                    // next pending prompt call to ensure no prompts get stuck.
                     const next = [...session.pendingMessages.entries()].sort((a, b) => a[1].order - b[1].order)[0];
                     if (next) {
                         next[1].resolve(false);
@@ -567,7 +937,7 @@ export class ClaudeAcpAgent {
     async cancel(params) {
         const session = this.sessions[params.sessionId];
         if (!session) {
-            throw new Error("Session not found");
+            return;
         }
         session.cancelled = true;
         for (const [, pending] of session.pendingMessages) {
@@ -576,23 +946,51 @@ export class ClaudeAcpAgent {
         session.pendingMessages.clear();
         await session.query.interrupt();
     }
-    async unstable_closeSession(params) {
-        const session = this.sessions[params.sessionId];
+    /** Cleanly tear down a session: cancel in-flight work, dispose resources,
+     *  and remove it from the session map. */
+    async teardownSession(sessionId) {
+        const session = this.sessions[sessionId];
         if (!session) {
-            throw new Error("Session not found");
+            return;
         }
-        await this.cancel({ sessionId: params.sessionId });
+        await this.cancel({ sessionId });
         session.settingsManager.dispose();
         session.abortController.abort();
-        delete this.sessions[params.sessionId];
+        session.query.close();
+        delete this.sessions[sessionId];
+    }
+    /** Tear down all active sessions. Called when the ACP connection closes. */
+    async dispose() {
+        await Promise.all(Object.keys(this.sessions).map((id) => this.teardownSession(id)));
+    }
+    async closeSession(params) {
+        if (!this.sessions[params.sessionId]) {
+            throw new Error("Session not found");
+        }
+        await this.teardownSession(params.sessionId);
+        return {};
+    }
+    async unstable_deleteSession(params) {
+        // Tear down any active in-memory state first so the on-disk file isn't
+        // recreated by an outstanding query writing to it.
+        if (this.sessions[params.sessionId]) {
+            await this.teardownSession(params.sessionId);
+        }
+        await deleteSession(params.sessionId);
         return {};
     }
     async unstable_setSessionModel(params) {
-        if (!this.sessions[params.sessionId]) {
+        const session = this.sessions[params.sessionId];
+        if (!session) {
             throw new Error("Session not found");
         }
-        await this.sessions[params.sessionId].query.setModel(params.modelId);
-        await this.updateConfigOption(params.sessionId, "model", params.modelId);
+        // Resolve aliases (e.g. "opus", "opus[1m]") to canonical model IDs so
+        // downstream lookups in modelInfos succeed and the effort option isn't
+        // silently dropped.
+        const resolved = resolveModelPreference(session.modelInfos, params.modelId);
+        const modelId = resolved?.value ?? params.modelId;
+        await session.query.setModel(modelId);
+        await this.updateConfigOption(params.sessionId, "model", modelId);
     }
     async setSessionMode(params) {
         if (!this.sessions[params.sessionId]) {
@@ -651,14 +1049,15 @@ export class ClaudeAcpAgent {
         else if (params.configId === "model") {
             await this.sessions[params.sessionId].query.setModel(resolvedValue);
         }
-        this.syncSessionConfigState(session, params.configId, params.value);
-        session.configOptions = session.configOptions.map((o) => o.id === params.configId && typeof o.currentValue === "string"
-            ? { ...o, currentValue: resolvedValue }
-            : o);
+        // Effort SDK sync is handled inside applyConfigOptionValue so that direct
+        // effort changes and effort changes induced by a model switch go through
+        // the same path.
+        await this.applyConfigOptionValue(params.sessionId, session, params.configId, resolvedValue);
         return { configOptions: session.configOptions };
     }
     async applySessionMode(sessionId, modeId) {
         switch (modeId) {
+            case "auto":
             case "default":
             case "acceptEdits":
             case "bypassPermissions":
@@ -668,8 +1067,15 @@ export class ClaudeAcpAgent {
             default:
                 throw new Error("Invalid Mode");
         }
+        const session = this.sessions[sessionId];
+        if (!session) {
+            throw new Error("Session not found");
+        }
+        if (!session.modes.availableModes.some((mode) => mode.id === modeId)) {
+            throw new Error(`Mode ${modeId} is not available in this session`);
+        }
         try {
-            await this.sessions[sessionId].query.setPermissionMode(modeId);
+            await session.query.setPermissionMode(modeId);
         }
         catch (error) {
             if (error instanceof Error) {
@@ -688,14 +1094,23 @@ export class ClaudeAcpAgent {
         const toolUseCache = {};
         const messages = await getSessionMessages(sessionId);
         for (const message of messages) {
+            // @ts-expect-error - untyped in SDK but we handle all of these
+            let content = message.message.content;
+            // @ts-expect-error - untyped in SDK but we handle all of these
+            if (message.message.role === "user") {
+                content = stripLocalCommandMetadata(content);
+                if (content === null)
+                    continue;
+            }
             for (const notification of toAcpNotifications(
             // @ts-expect-error - untyped in SDK but we handle all of these
-            message.message.content, 
+            content, 
             // @ts-expect-error - untyped in SDK but we handle all of these
             message.message.role, sessionId, toolUseCache, this.client, this.logger, {
                 registerHooks: false,
                 clientCapabilities: this.clientCapabilities,
                 cwd: this.sessions[sessionId]?.cwd,
+                taskState: this.sessions[sessionId]?.taskState,
             })) {
                 await this.client.sessionUpdate(notification);
             }
@@ -711,6 +1126,7 @@ export class ClaudeAcpAgent {
     }
     canUseTool(sessionId) {
         return async (toolName, toolInput, { signal, suggestions, toolUseID }) => {
+            const alwaysAllowLabel = describeAlwaysAllow(suggestions, toolName);
             const supportsTerminalOutput = this.clientCapabilities?._meta?.["terminal_output"] === true;
             const session = this.sessions[sessionId];
             if (!session) {
@@ -720,7 +1136,8 @@ export class ClaudeAcpAgent {
                 };
             }
             if (toolName === "ExitPlanMode") {
-                const options = [
+                const optionsAll = [
+                    { kind: "allow_always", name: 'Yes, and use "auto" mode', optionId: "auto" },
                     {
                         kind: "allow_always",
                         name: "Yes, and auto-accept edits",
@@ -730,12 +1147,18 @@ export class ClaudeAcpAgent {
                     { kind: "reject_once", name: "No, keep planning", optionId: "plan" },
                 ];
                 if (ALLOW_BYPASS) {
-                    options.unshift({
+                    optionsAll.unshift({
                         kind: "allow_always",
                         name: "Yes, and bypass permissions",
                         optionId: "bypassPermissions",
                     });
                 }
+                // Filter against the session's currently-advertised modes so we never
+                // present options the active model can't honor (e.g. `auto` on Haiku).
+                // `bypassPermissions` is already covered by `availableModes` via
+                // `buildAvailableModes`/`ALLOW_BYPASS`. The `plan` option is a
+                // "keep planning" reject path; it's always present in `availableModes`.
+                const options = optionsAll.filter((o) => session.modes.availableModes.some((m) => m.id === o.optionId));
                 const response = await this.client.requestPermission({
                     options,
                     sessionId,
@@ -748,23 +1171,26 @@ export class ClaudeAcpAgent {
                 if (signal.aborted || response.outcome?.outcome === "cancelled") {
                     throw new Error("Tool use aborted");
                 }
-                if (response.outcome?.outcome === "selected" &&
-                    (response.outcome.optionId === "default" ||
-                        response.outcome.optionId === "acceptEdits" ||
-                        response.outcome.optionId === "bypassPermissions")) {
+                const selectedMode = response.outcome?.outcome === "selected" ? response.outcome.optionId : undefined;
+                const selectedModeWasOffered = options.some((option) => option.optionId === selectedMode);
+                if (selectedModeWasOffered &&
+                    (selectedMode === "default" ||
+                        selectedMode === "acceptEdits" ||
+                        selectedMode === "auto" ||
+                        selectedMode === "bypassPermissions")) {
                     await this.client.sessionUpdate({
                         sessionId,
                         update: {
                             sessionUpdate: "current_mode_update",
-                            currentModeId: response.outcome.optionId,
+                            currentModeId: selectedMode,
                         },
                     });
-                    await this.updateConfigOption(sessionId, "mode", response.outcome.optionId);
+                    await this.updateConfigOption(sessionId, "mode", selectedMode);
                     return {
                         behavior: "allow",
                         updatedInput: toolInput,
                         updatedPermissions: suggestions ?? [
-                            { type: "setMode", mode: response.outcome.optionId, destination: "session" },
+                            { type: "setMode", mode: selectedMode, destination: "session" },
                         ],
                     };
                 }
@@ -788,7 +1214,7 @@ export class ClaudeAcpAgent {
                 options: [
                     {
                         kind: "allow_always",
-                        name: "Always Allow",
+                        name: alwaysAllowLabel,
                         optionId: "allow_always",
                     },
                     { kind: "allow_once", name: "Allow", optionId: "allow" },
@@ -851,8 +1277,7 @@ export class ClaudeAcpAgent {
         const session = this.sessions[sessionId];
         if (!session)
             return;
-        this.syncSessionConfigState(session, configId, value);
-        session.configOptions = session.configOptions.map((o) => o.id === configId && typeof o.currentValue === "string" ? { ...o, currentValue: value } : o);
+        await this.applyConfigOptionValue(sessionId, session, configId, value);
         await this.client.sessionUpdate({
             sessionId,
             update: {
@@ -861,27 +1286,107 @@ export class ClaudeAcpAgent {
             },
         });
     }
-    syncSessionConfigState(session, configId, value) {
+    async applyConfigOptionValue(sessionId, session, configId, value) {
         if (configId === "mode") {
             session.modes = { ...session.modes, currentModeId: value };
+            session.configOptions = session.configOptions.map((o) => o.id === configId && typeof o.currentValue === "string" ? { ...o, currentValue: value } : o);
         }
         else if (configId === "model") {
+            if (session.models.currentModelId !== value) {
+                // The cached context window was learned for the previous model; reset
+                // to the new model's heuristic so mid-stream updates between now and
+                // the next `result` reflect the user's selection instead of the old
+                // model's window.
+                session.contextWindowSize = inferContextWindowFromModel(value) ?? DEFAULT_CONTEXT_WINDOW;
+            }
             session.models = { ...session.models, currentModelId: value };
+            // Recompute availableModes for the new model and clamp the current
+            // mode if the SDK no longer offers it (today: "auto" on Haiku).
+            // `ModelInfo.supportsAutoMode` is the canonical SDK signal.
+            const newModelInfo = session.modelInfos.find((m) => m.value === value);
+            const newAvailableModes = buildAvailableModes(newModelInfo);
+            // Capture BEFORE mutating session.modes so the log message reflects
+            // the invalidated mode rather than "default".
+            const previousModeId = session.modes.currentModeId;
+            let modeDowngraded = false;
+            if (!newAvailableModes.some((m) => m.id === previousModeId)) {
+                session.modes = {
+                    availableModes: newAvailableModes,
+                    currentModeId: "default",
+                };
+                try {
+                    await session.query.setPermissionMode("default");
+                }
+                catch (err) {
+                    // Failing the entire model switch over a bookkeeping sync error is
+                    // worse UX than logging and continuing; the user explicitly asked
+                    // to change models. The next setPermissionMode from the user will
+                    // either succeed or surface a fresh error.
+                    this.logger.error(`Failed to sync permissionMode to "default" after model switch invalidated "${previousModeId}":`, err);
+                }
+                modeDowngraded = true;
+            }
+            else {
+                session.modes = { ...session.modes, availableModes: newAvailableModes };
+            }
+            // Rebuild config options since effort levels depend on the selected model
+            const effortOpt = session.configOptions.find((o) => o.id === "effort");
+            const currentEffort = typeof effortOpt?.currentValue === "string" ? effortOpt.currentValue : undefined;
+            session.configOptions = buildConfigOptions(session.modes, session.models, session.modelInfos, currentEffort);
+            // Sync effort with the SDK if it changed after the model switch
+            const newEffortOpt = session.configOptions.find((o) => o.id === "effort");
+            const newEffort = typeof newEffortOpt?.currentValue === "string" ? newEffortOpt.currentValue : undefined;
+            if (newEffort !== currentEffort) {
+                await session.query.applyFlagSettings({
+                    effortLevel: toSdkEffortLevel(newEffort),
+                });
+            }
+            // Emit current_mode_update only after session.modes AND
+            // session.configOptions have been fully reconciled. This way, a failure
+            // in the configOptions/effort rebuild above can't leave the client with
+            // a clamped currentModeId but stale configOptions, and the notification
+            // still precedes the caller's config_option_update so order-sensitive
+            // clients update currentModeId before re-rendering the option list.
+            if (modeDowngraded) {
+                await this.client.sessionUpdate({
+                    sessionId,
+                    update: {
+                        sessionUpdate: "current_mode_update",
+                        currentModeId: "default",
+                    },
+                });
+            }
+        }
+        else {
+            session.configOptions = session.configOptions.map((o) => o.id === configId && typeof o.currentValue === "string" ? { ...o, currentValue: value } : o);
+            if (configId === "effort") {
+                await session.query.applyFlagSettings({
+                    effortLevel: toSdkEffortLevel(value),
+                });
+            }
         }
     }
     async getOrCreateSession(params) {
         const existingSession = this.sessions[params.sessionId];
         if (existingSession) {
-            return {
-                sessionId: params.sessionId,
-                modes: existingSession.modes,
-                models: existingSession.models,
-                configOptions: existingSession.configOptions,
-            };
+            const fingerprint = computeSessionFingerprint(params);
+            if (fingerprint === existingSession.sessionFingerprint) {
+                return {
+                    sessionId: params.sessionId,
+                    modes: existingSession.modes,
+                    models: existingSession.models,
+                    configOptions: existingSession.configOptions,
+                };
+            }
+            // Session-defining params changed (e.g. cwd pointed at a git worktree,
+            // or MCP servers reconfigured). Tear down the existing session and
+            // recreate it so the underlying Query process picks up the new values.
+            await this.teardownSession(params.sessionId);
         }
         const response = await this.createSession({
             cwd: params.cwd,
             mcpServers: params.mcpServers ?? [],
+            additionalDirectories: params.additionalDirectories,
             _meta: params._meta,
         }, {
             resume: params.sessionId,
@@ -924,7 +1429,7 @@ export class ClaudeAcpAgent {
                             : undefined,
                     };
                 }
-                else {
+                else if (!("type" in server)) {
                     // Stdio type MCP server (with or without explicit type field)
                     mcpServers[server.name] = {
                         type: "stdio",
@@ -944,12 +1449,18 @@ export class ClaudeAcpAgent {
                 systemPrompt = customPrompt;
             }
             else if (typeof customPrompt === "object" &&
-                "append" in customPrompt &&
-                typeof customPrompt.append === "string") {
-                systemPrompt.append = customPrompt.append;
+                customPrompt !== null &&
+                !Array.isArray(customPrompt)) {
+                // Forward all preset options (append, excludeDynamicSections, and
+                // anything the SDK adds later) while locking type/preset.
+                systemPrompt = {
+                    ...customPrompt,
+                    type: "preset",
+                    preset: "claude_code",
+                };
             }
         }
-        const permissionMode = resolvePermissionMode(settingsManager.getSettings().permissions?.defaultMode);
+        const permissionMode = resolvePermissionMode(settingsManager.getSettings().permissions?.defaultMode, this.logger);
         // Extract options from _meta if provided
         const sessionMeta = params._meta;
         const userProvidedOptions = sessionMeta?.claudeCode?.options;
@@ -957,8 +1468,10 @@ export class ClaudeAcpAgent {
         const maxThinkingTokens = process.env.MAX_THINKING_TOKENS
             ? parseInt(process.env.MAX_THINKING_TOKENS, 10)
             : undefined;
+        // Parse model configuration from environment (e.g. Bedrock model overrides)
+        const modelConfig = parseModelConfig(process.env.CLAUDE_MODEL_CONFIG);
         // Disable this for now, not a great way to expose this over ACP at the moment (in progress work so we can revisit)
-        const disallowedTools = ["AskUserQuestion"];
+        const disallowedTools = ["AskUserQuestion", "WebFetch", "WebSearch"];
         // Resolve which built-in tools to expose.
         // Explicit tools array from _meta.claudeCode.options takes precedence.
         // disableBuiltInTools is a legacy shorthand for tools: [] — kept for
@@ -966,15 +1479,30 @@ export class ClaudeAcpAgent {
         const tools = userProvidedOptions?.tools ??
             (params._meta?.disableBuiltInTools === true ? [] : { type: "preset", preset: "claude_code" });
         const abortController = userProvidedOptions?.abortController || new AbortController();
+        // Per-session task state. Created here (rather than in the session record
+        // below) so the TaskCreated/TaskCompleted hook callbacks can close over
+        // the same Map that the streaming message handler will read from.
+        const taskState = new Map();
         const options = {
             systemPrompt,
             settingSources: ["user", "project", "local"],
             ...(maxThinkingTokens !== undefined && { maxThinkingTokens }),
             ...userProvidedOptions,
+            // CLAUDE_MODEL_CONFIG env var is a fallback for model
+            // configuration (e.g. Bedrock model ID overrides). When the caller
+            // provides settings via _meta, we intentionally ignore the env var —
+            // the caller is assumed to have full control over model configuration.
+            ...(!userProvidedOptions?.settings &&
+                modelConfig && {
+                settings: {
+                    ...(modelConfig.modelOverrides && { modelOverrides: modelConfig.modelOverrides }),
+                    ...(modelConfig.availableModels && { availableModels: modelConfig.availableModels }),
+                },
+            }),
             env: {
                 ...process.env,
                 ...userProvidedOptions?.env,
-                ...createEnvForGateway(this.gatewayAuthMeta),
+                ...createEnvForGateway(this.gatewayAuthRequest),
                 // Opt-in to session state events like when the agent is idle
                 CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS: "1",
             },
@@ -987,14 +1515,7 @@ export class ClaudeAcpAgent {
             allowDangerouslySkipPermissions: ALLOW_BYPASS,
             permissionMode,
             canUseTool: this.canUseTool(sessionId),
-            // note: although not documented by the types, passing an absolute path
-            // here works to find zed's managed node version.
-            executable: isStaticBinary() ? undefined : process.execPath,
-            ...(process.env.CLAUDE_CODE_EXECUTABLE
-                ? { pathToClaudeCodeExecutable: process.env.CLAUDE_CODE_EXECUTABLE }
-                : isStaticBinary()
-                    ? { pathToClaudeCodeExecutable: await claudeCliPath() }
-                    : {}),
+            pathToClaudeCodeExecutable: process.env.CLAUDE_CODE_EXECUTABLE ?? (await claudeCliPath()),
             extraArgs: {
                 ...userProvidedOptions?.extraArgs,
                 "replay-user-messages": "",
@@ -1022,13 +1543,56 @@ export class ClaudeAcpAgent {
                         ],
                     },
                 ],
+                TaskCreated: [
+                    ...(userProvidedOptions?.hooks?.TaskCreated || []),
+                    {
+                        hooks: [
+                            createTaskHook({
+                                taskState,
+                                onChange: async () => {
+                                    await this.client.sessionUpdate({
+                                        sessionId,
+                                        update: {
+                                            sessionUpdate: "plan",
+                                            entries: taskStateToPlanEntries(taskState),
+                                        },
+                                    });
+                                },
+                            }),
+                        ],
+                    },
+                ],
+                TaskCompleted: [
+                    ...(userProvidedOptions?.hooks?.TaskCompleted || []),
+                    {
+                        hooks: [
+                            createTaskHook({
+                                taskState,
+                                onChange: async () => {
+                                    await this.client.sessionUpdate({
+                                        sessionId,
+                                        update: {
+                                            sessionUpdate: "plan",
+                                            entries: taskStateToPlanEntries(taskState),
+                                        },
+                                    });
+                                },
+                            }),
+                        ],
+                    },
+                ],
             },
             ...creationOpts,
             abortController,
         };
+        // Prefer the official ACP `additionalDirectories` field. Fall back to the
+        // legacy `_meta.additionalRoots` extension for clients that haven't been
+        // updated yet. Either source is merged with directories supplied via
+        // `_meta.claudeCode.options.additionalDirectories` (SDK pass-through).
+        const acpAdditionalDirectories = params.additionalDirectories ?? sessionMeta?.additionalRoots ?? [];
         options.additionalDirectories = [
             ...(userProvidedOptions?.additionalDirectories ?? []),
-            ...(sessionMeta?.additionalRoots ?? []),
+            ...acpAdditionalDirectories,
         ];
         if (creationOpts?.resume === undefined || creationOpts?.forkSession) {
             // Set our own session id if not resuming an existing session.
@@ -1038,15 +1602,6 @@ export class ClaudeAcpAgent {
         if (abortController?.signal.aborted) {
             throw new Error("Cancelled");
         }
-        // ==================== 会话创建开始 ====================
-        const sessionCreateStartTime = Date.now();
-        this.logger.log(`🔵 [ACP] 开始创建会话`);
-        this.logger.log(`   ├─ sessionId: ${sessionId}`);
-        this.logger.log(`   ├─ cwd: ${params.cwd}`);
-        this.logger.log(`   └─ MCP 服务器数量: ${Object.keys(mcpServers).length}`);
-        if (Object.keys(mcpServers).length > 0) {
-            this.logger.log(`   └─ MCP 服务器列表: ${Object.keys(mcpServers).join(", ")}`);
-        }
         const q = query({
             prompt: input,
             options,
@@ -1058,59 +1613,78 @@ export class ClaudeAcpAgent {
         catch (error) {
             if (creationOpts.resume &&
                 error instanceof Error &&
-                error.message === "Query closed before response received") {
+                (error.message === "Query closed before response received" ||
+                    error.message.includes("No conversation found with session ID"))) {
                 throw RequestError.resourceNotFound(sessionId);
             }
             throw error;
         }
         if (shouldHideClaudeAuth() &&
             initializationResult.account.subscriptionType &&
-            !this.gatewayAuthMeta) {
+            !this.gatewayAuthRequest) {
             throw RequestError.authRequired(undefined, "This integration does not support using claude.ai subscriptions.");
         }
-        const models = await getAvailableModels(q, initializationResult.models, settingsManager);
-        const sessionCreateElapsed = Date.now() - sessionCreateStartTime;
-        this.logger.log(`✅ [ACP] 会话创建完成, 总耗时: ${sessionCreateElapsed}ms`);
-        const availableModes = [
-            {
-                id: "default",
-                name: "Default",
-                description: "Standard behavior, prompts for dangerous operations",
-            },
-            {
-                id: "acceptEdits",
-                name: "Accept Edits",
-                description: "Auto-accept file edit operations",
-            },
-            {
-                id: "plan",
-                name: "Plan Mode",
-                description: "Planning mode, no actual tool execution",
-            },
-            {
-                id: "dontAsk",
-                name: "Don't Ask",
-                description: "Don't prompt for permissions, deny if not pre-approved",
-            },
-        ];
-        // Only works in non-root mode
-        if (ALLOW_BYPASS) {
-            availableModes.push({
-                id: "bypassPermissions",
-                name: "Bypass Permissions",
-                description: "Bypass all permission checks",
-            });
+        // Apply user's `availableModels` allowlist from settings.json before any
+        // downstream model handling. The SDK only enforces this allowlist in its
+        // own UI, not in `initializationResult.models`, so we filter here to keep
+        // configOptions, the current-model resolver, and the stored modelInfos
+        // consistent with what the user configured.
+        const settingsAvailableModels = settingsManager.getSettings().availableModels;
+        const allowedModels = Array.isArray(settingsAvailableModels)
+            ? applyAvailableModelsAllowlist(initializationResult.models, settingsAvailableModels)
+            : initializationResult.models;
+        const models = await getAvailableModels(q, allowedModels, initializationResult.models, settingsManager, this.logger);
+        // Gate `auto` (and future model-specific modes) on the resolved model's
+        // `ModelInfo`. See `buildAvailableModes` for the canonical SDK signal.
+        const currentModelInfo = allowedModels.find((m) => m.value === models.currentModelId);
+        const availableModes = buildAvailableModes(currentModelInfo);
+        // Clamp `permissionMode` if the resolved session does not offer it. The
+        // common case is `permissions.defaultMode: "auto"` resolving to a model
+        // that does not support auto mode (e.g. Haiku); without this clamp the
+        // SDK would later throw `"auto mode unavailable for this model"` from
+        // `setPermissionMode`. Keep `permissionMode` as the resolved user intent
+        // (matches what was passed into `options.permissionMode` above) and use
+        // `effectiveMode` for the post-clamp value the session actually runs in.
+        let effectiveMode = permissionMode;
+        if (!availableModes.some((m) => m.id === effectiveMode)) {
+            if (effectiveMode === "auto") {
+                this.logger.error(`permissions.defaultMode "auto" is not available for model ` +
+                    `"${models.currentModelId}"; falling back to "default".`);
+            }
+            else {
+                this.logger.error(`permissions.defaultMode "${effectiveMode}" is not available in ` +
+                    `this session; falling back to "default".`);
+            }
+            effectiveMode = "default";
+            // Sync the SDK so it doesn't keep "auto" cached internally. Wrapped in
+            // try/catch since failing here would abort session creation entirely.
+            try {
+                await q.setPermissionMode("default");
+            }
+            catch (err) {
+                this.logger.error("Failed to sync clamped permissionMode to SDK:", err);
+            }
         }
         const modes = {
-            currentModeId: permissionMode,
+            currentModeId: effectiveMode,
             availableModes,
         };
-        const configOptions = buildConfigOptions(modes, models);
+        const configOptions = buildConfigOptions(modes, models, allowedModels, settingsManager.getSettings().effortLevel);
+        // Apply the initial effort level to the SDK so it matches the UI default
+        const initialEffort = configOptions.find((o) => o.id === "effort");
+        if (initialEffort &&
+            typeof initialEffort.currentValue === "string" &&
+            initialEffort.currentValue !== "default") {
+            await q.applyFlagSettings({
+                effortLevel: initialEffort.currentValue,
+            });
+        }
         this.sessions[sessionId] = {
             query: q,
             input: input,
             cancelled: false,
             cwd: params.cwd,
+            sessionFingerprint: computeSessionFingerprint(params),
             settingsManager,
             accumulatedUsage: {
                 inputTokens: 0,
@@ -1120,11 +1694,15 @@ export class ClaudeAcpAgent {
             },
             modes,
             models,
+            modelInfos: allowedModels,
             configOptions,
             promptRunning: false,
             pendingMessages: new Map(),
             nextPendingOrder: 0,
             abortController,
+            emitRawSDKMessages: sessionMeta?.claudeCode?.emitRawSDKMessages ?? false,
+            contextWindowSize: inferContextWindowFromModel(models.currentModelId) ?? DEFAULT_CONTEXT_WINDOW,
+            taskState,
         };
         return {
             sessionId,
@@ -1134,6 +1712,15 @@ export class ClaudeAcpAgent {
         };
     }
 }
+function shouldEmitRawMessage(config, message) {
+    if (config === true)
+        return true;
+    if (config === false)
+        return false;
+    return config.some((f) => f.type === message.type &&
+        (f.subtype === undefined || f.subtype === message.subtype) &&
+        (f.origin === undefined || f.origin === message.origin?.kind));
+}
 function sessionUsage(session) {
     return {
         inputTokens: session.accumulatedUsage.inputTokens,
@@ -1146,20 +1733,119 @@ function sessionUsage(session) {
             session.accumulatedUsage.cachedWriteTokens,
     };
 }
-function createEnvForGateway(gatewayMeta) {
-    if (!gatewayMeta) {
+/** Sum all four fields as a proxy for post-turn context occupancy: the current
+ *  turn's output becomes next turn's input. Per the Anthropic API, input_tokens
+ *  excludes cache tokens — cache_read and cache_creation are reported
+ *  separately — so summing all four is not double-counting. */
+function totalTokens(usage) {
+    return (usage.input_tokens +
+        usage.output_tokens +
+        usage.cache_read_input_tokens +
+        usage.cache_creation_input_tokens);
+}
+/**
+ * Build the `data` payload attached to a `RequestError.internalError` when we
+ * have a categorical error from the Claude SDK. Returns `undefined` when no
+ * categorical error is available, matching the previous behavior of passing
+ * `undefined` to `RequestError.internalError`.
+ *
+ * The `errorKind` field is a convention for ACP clients to dispatch on
+ * without having to pattern-match the human-readable message text. Clients
+ * that don't understand it fall back to the existing message-based rendering.
+ */
+function errorKindData(errorKind) {
+    return errorKind ? { errorKind } : undefined;
+}
+/** Project a nullable API usage object into our non-null snapshot shape.
+ *  Both SDK message_start and assistant message `usage` have `number | null`
+ *  cache fields; we coerce absent values to 0 so `totalTokens` never hits
+ *  NaN. `input_tokens`/`output_tokens` are typed `number` by the SDK but
+ *  synthetic or third-party-backend stream events have been observed emitting
+ *  them as null/undefined — coerce those too so a malformed upstream event
+ *  can't leak NaN into the wire `used` field. Delta events have different
+ *  semantics (cumulative + prev fallback) and are handled inline. */
+function snapshotFromUsage(usage) {
+    return {
+        input_tokens: usage.input_tokens ?? 0,
+        output_tokens: usage.output_tokens ?? 0,
+        cache_read_input_tokens: usage.cache_read_input_tokens ?? 0,
+        cache_creation_input_tokens: usage.cache_creation_input_tokens ?? 0,
+    };
+}
+function createEnvForGateway(request) {
+    if (!request?._meta) {
         return {};
     }
+    const customHeaders = Object.entries(request._meta.gateway.headers)
+        .map(([key, value]) => `${key}: ${value}`)
+        .join("\n");
+    if (request.methodId === "gateway-bedrock") {
+        return {
+            CLAUDE_CODE_USE_BEDROCK: "1",
+            AWS_BEARER_TOKEN_BEDROCK: " ", // Must be non-empty to bypass pass configuration check
+            ANTHROPIC_BEDROCK_BASE_URL: request._meta.gateway.baseUrl,
+            ANTHROPIC_CUSTOM_HEADERS: customHeaders,
+        };
+    }
     return {
-        ANTHROPIC_BASE_URL: gatewayMeta.gateway.baseUrl,
-        ANTHROPIC_CUSTOM_HEADERS: Object.entries(gatewayMeta.gateway.headers)
-            .map(([key, value]) => `${key}: ${value}`)
-            .join("\n"),
-        ANTHROPIC_AUTH_TOKEN: "", // Must be specified to bypass claude login requirement
+        ANTHROPIC_BASE_URL: request._meta.gateway.baseUrl,
+        ANTHROPIC_CUSTOM_HEADERS: customHeaders,
+        ANTHROPIC_AUTH_TOKEN: " ", // Must be specified to bypass claude login requirement
     };
 }
-function buildConfigOptions(modes, models) {
-    return [
+/**
+ * Build the list of permission modes the agent will advertise for the given
+ * model. `auto` is gated by `ModelInfo.supportsAutoMode === true`, which is
+ * the SDK's model-level availability signal. `undefined`/`false` both exclude
+ * `auto`. `bypassPermissions` is still gated by `ALLOW_BYPASS`.
+ */
+function buildAvailableModes(modelInfo) {
+    const modes = [];
+    // Only advertise "auto" when the SDK reports the model supports it.
+    if (modelInfo?.supportsAutoMode === true) {
+        modes.push({
+            id: "auto",
+            name: "Auto",
+            description: "Use a model classifier to approve/deny permission prompts",
+        });
+    }
+    modes.push({
+        id: "default",
+        name: "Default",
+        description: "Standard behavior, prompts for dangerous operations",
+    }, {
+        id: "acceptEdits",
+        name: "Accept Edits",
+        description: "Auto-accept file edit operations",
+    }, {
+        id: "plan",
+        name: "Plan Mode",
+        description: "Planning mode, no actual tool execution",
+    }, {
+        id: "dontAsk",
+        name: "Don't Ask",
+        description: "Don't prompt for permissions, deny if not pre-approved",
+    });
+    if (ALLOW_BYPASS) {
+        modes.push({
+            id: "bypassPermissions",
+            name: "Bypass Permissions",
+            description: "Bypass all permission checks",
+        });
+    }
+    return modes;
+}
+// Translate a UI effort value into the flag-layer payload. The SDK
+// shallow-merges `applyFlagSettings`, drops `undefined` during JSON transport,
+// and only clears a key when an explicit `null` is sent — see
+// `applyFlagSettings` in @anthropic-ai/claude-agent-sdk. Mapping both the
+// `"default"` sentinel and `undefined` (effort option absent for the model) to
+// `null` ensures any previously-applied flag is actually cleared.
+function toSdkEffortLevel(value) {
+    return value === undefined || value === "default" ? null : value;
+}
+function buildConfigOptions(modes, models, modelInfos, currentEffortLevel) {
+    const options = [
         {
             id: "mode",
             name: "Mode",
@@ -1187,10 +1873,58 @@ function buildConfigOptions(modes, models) {
             })),
         },
     ];
+    // Add effort level option based on the currently selected model
+    const currentModelInfo = modelInfos.find((m) => m.value === models.currentModelId);
+    const supportedLevels = currentModelInfo?.supportsEffort
+        ? (currentModelInfo.supportedEffortLevels ?? [])
+        : [];
+    if (supportedLevels.length > 0) {
+        const effortOptions = [
+            { value: "default", name: "Default" },
+            ...supportedLevels.map((level) => ({
+                value: level,
+                name: level
+                    .split(/[_-]/)
+                    .map((part) => (part ? part.charAt(0).toUpperCase() + part.slice(1) : part))
+                    .join(" "),
+            })),
+        ];
+        const includes = (l) => l === "default" || supportedLevels.includes(l);
+        const validEffort = currentEffortLevel && includes(currentEffortLevel) ? currentEffortLevel : "default";
+        options.push({
+            id: "effort",
+            name: "Effort",
+            description: "Available effort levels for this model",
+            category: "thought_level",
+            type: "select",
+            currentValue: validEffort,
+            options: effortOptions,
+        });
+    }
+    return options;
 }
 // Claude Code CLI persists display strings like "opus[1m]" in settings,
 // but the SDK model list uses IDs like "claude-opus-4-6-1m".
 const MODEL_CONTEXT_HINT_PATTERN = /\[(\d+m)\]$/i;
+// Captures a model family version such as `4-6` or `4.7` so we can keep
+// `claude-opus-4-6` from being copied onto the SDK's `opus` alias when that
+// alias currently resolves to a different family version (e.g. Opus 4.7).
+const MODEL_FAMILY_VERSION_PATTERN = /\b(\d+)[-.](\d+)\b/;
+function extractModelFamilyVersion(s) {
+    const match = s.match(MODEL_FAMILY_VERSION_PATTERN);
+    return match ? `${match[1]}.${match[2]}` : null;
+}
+function modelVersionsCompatible(preference, candidate) {
+    const preferred = extractModelFamilyVersion(preference);
+    if (!preferred)
+        return true;
+    const candidateVersion = extractModelFamilyVersion(candidate.value) ??
+        extractModelFamilyVersion(candidate.displayName) ??
+        extractModelFamilyVersion(candidate.description);
+    if (!candidateVersion)
+        return true;
+    return preferred === candidateVersion;
+}
 function tokenizeModelPreference(model) {
     const lower = model.trim().toLowerCase();
     const contextHint = lower.match(MODEL_CONTEXT_HINT_PATTERN)?.[1]?.toLowerCase();
@@ -1231,6 +1965,8 @@ function resolveModelPreference(models, preference) {
         return directMatch;
     // Substring match
     const includesMatch = models.find((model) => {
+        if (!modelVersionsCompatible(trimmed, model))
+            return false;
         const value = model.value.toLowerCase();
         const display = model.displayName.toLowerCase();
         return value.includes(lower) || display.includes(lower) || lower.includes(value);
@@ -1244,6 +1980,8 @@ function resolveModelPreference(models, preference) {
     let bestMatch = null;
     let bestScore = 0;
     for (const model of models) {
+        if (!modelVersionsCompatible(trimmed, model))
+            continue;
         const score = scoreModelMatch(model, tokens, contextHint);
         if (0 < score && (!bestMatch || bestScore < score)) {
             bestMatch = model;
@@ -1252,26 +1990,98 @@ function resolveModelPreference(models, preference) {
     }
     return bestMatch;
 }
-async function getAvailableModels(query, models, settingsManager) {
+function resolveSettingsModel(models, settingsModel, logger) {
+    if (settingsModel === undefined) {
+        return null;
+    }
+    if (typeof settingsModel !== "string") {
+        const typeLabel = settingsModel === null ? "null" : typeof settingsModel;
+        logger.error(`Ignoring model from settings: expected a string, got ${typeLabel}.`);
+        return null;
+    }
+    return resolveModelPreference(models, settingsModel);
+}
+/**
+ * Restrict the SDK's model list to the user's `availableModels` allowlist
+ * (already merged-and-deduped across settings sources by `SettingsManager`).
+ * The user's exact entries become the model IDs surfaced via configOptions
+ * and passed to `setModel`, which prevents Claude Code from silently
+ * substituting a date-pinned variant (e.g. `haiku` →
+ * `claude-haiku-4-5-20251001`) that the user may not have access to.
+ *
+ * Display info and capability flags are copied from the closest SDK match so
+ * the UI still renders sensible names and effort levels.
+ *
+ * Semantics from https://code.claude.com/docs/en/model-config#restrict-model-selection:
+ * - `undefined` is handled by the caller (no allowlist applied).
+ * - The Default option is unaffected by `availableModels` — it always remains
+ *   available, even when the allowlist is `[]`.
+ */
+function applyAvailableModelsAllowlist(sdkModels, allowlist) {
+    // Default is always preserved per the docs. Synthesize one if the SDK
+    // didn't surface it so downstream code (e.g. `getAvailableModels` picking
+    // `models[0]` as a fallback) still has something to work with.
+    const defaultModel = sdkModels.find((m) => m.value === "default") ?? {
+        value: "default",
+        displayName: "Default",
+        description: "",
+    };
+    const result = [defaultModel];
+    const seen = new Set([defaultModel.value]);
+    const sdkModelsWithoutDefault = sdkModels.filter((m) => m.value !== "default");
+    for (const entry of allowlist) {
+        const trimmed = entry.trim();
+        if (!trimmed || seen.has(trimmed))
+            continue;
+        const sdkMatch = resolveModelPreference(sdkModelsWithoutDefault, trimmed);
+        if (sdkMatch) {
+            result.push({ ...sdkMatch, value: trimmed });
+        }
+        else {
+            result.push({ value: trimmed, displayName: trimmed, description: "" });
+        }
+        seen.add(trimmed);
+    }
+    return result;
+}
+async function getAvailableModels(query, models, sdkModels, settingsManager, logger) {
     const settings = settingsManager.getSettings();
     let currentModel = models[0];
-    // 模型优先级（从高到低）：
-    // 1. ANTHROPIC_MODEL 环境变量（用户期望的最高优先级）
-    // 2. settings.model（用户配置文件）
-    // 3. models[0]（默认使用第一个模型）
+    let resolvedFromInput;
+    // Model priority (highest to lowest):
+    // 1. ANTHROPIC_MODEL environment variable
+    // 2. settings.model (user configuration)
+    // 3. models[0] (default first model)
     if (process.env.ANTHROPIC_MODEL) {
         const match = resolveModelPreference(models, process.env.ANTHROPIC_MODEL);
         if (match) {
             currentModel = match;
+            resolvedFromInput = process.env.ANTHROPIC_MODEL;
         }
     }
-    else if (settings.model) {
-        const match = resolveModelPreference(models, settings.model);
+    else if (typeof settings.model === "string") {
+        const match = resolveSettingsModel(models, settings.model, logger);
         if (match) {
             currentModel = match;
+            resolvedFromInput = settings.model;
         }
     }
-    await query.setModel(currentModel.value);
+    // Skip the setModel round-trip when we can prove the SDK has already landed
+    // on the same model. Two cases qualify:
+    //  (a) No override applied — currentModel stayed at models[0]; the SDK is on
+    //      its own default and we have nothing to sync.
+    //  (b) The resolver returned the user's input verbatim AND that value exists
+    //      in the SDK's original model list — meaning no fuzzy match or
+    //      allowlist rewrite was involved, and the SDK (which reads the same
+    //      ANTHROPIC_MODEL / settings.json) will have arrived at the same entry.
+    // Anything else (fuzzy match, allowlist-synthesized value, alias) gets a
+    // setModel call so we don't drift from the user's intended pin.
+    const sdkSawSameValue = sdkModels.some((m) => m.value === currentModel.value);
+    const skipSetModel = resolvedFromInput === undefined ||
+        (currentModel.value === resolvedFromInput && sdkSawSameValue);
+    if (!skipSetModel) {
+        await query.setModel(currentModel.value);
+    }
     return {
         availableModels: models.map((model) => ({
             modelId: model.value,
@@ -1283,6 +2093,7 @@ async function getAvailableModels(query, models, settingsManager) {
 }
 function getAvailableSlashCommands(commands) {
     const UNSUPPORTED_COMMANDS = [
+        "clear",
         "cost",
         "keybindings-help",
         "login",
@@ -1411,6 +2222,7 @@ export function promptToClaude(prompt) {
  * Only handles text, image, and thinking chunks for now.
  */
 export function toAcpNotifications(content, role, sessionId, toolUseCache, client, logger, options) {
+    const taskState = options?.taskState ?? new Map();
     const registerHooks = options?.registerHooks !== false;
     const supportsTerminalOutput = options?.clientCapabilities?._meta?.["terminal_output"] === true;
     if (typeof content === "string") {
@@ -1474,14 +2286,22 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                 const alreadyCached = chunk.id in toolUseCache;
                 toolUseCache[chunk.id] = chunk;
                 if (chunk.name === "TodoWrite") {
-                    // @ts-expect-error - sometimes input is empty object
-                    if (Array.isArray(chunk.input.todos)) {
+                    // @ts-expect-error - sometimes input is empty object or undefined
+                    if (Array.isArray(chunk.input?.todos)) {
                         update = {
                             sessionUpdate: "plan",
                             entries: planEntries(chunk.input),
                         };
                     }
                 }
+                else if (chunk.name === "TaskCreate" ||
+                    chunk.name === "TaskUpdate" ||
+                    chunk.name === "TaskList" ||
+                    chunk.name === "TaskGet") {
+                    // Task* tool_use is suppressed; the plan update is emitted at
+                    // tool_result time once we have the task ID (for TaskCreate) and
+                    // confirmation that the change took effect.
+                }
                 else {
                     // Only register hooks on first encounter to avoid double-firing
                     if (registerHooks && !alreadyCached) {
@@ -1489,7 +2309,17 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                             onPostToolUseHook: async (toolUseId, toolInput, toolResponse) => {
                                 const toolUse = toolUseCache[toolUseId];
                                 if (toolUse) {
-                                    const editDiff = toolUse.name === "Edit" ? toolUpdateFromEditToolResponse(toolResponse) : {};
+                                    // Both `Edit` and `Write` produce a structuredPatch in their
+                                    // PostToolUse tool_response. For Edit the diff replaces the
+                                    // optimistic content built at tool_use time. For Write the
+                                    // optimistic content (built from `input.content` alone with
+                                    // `oldText: null`) shows "creation" semantics regardless of
+                                    // whether the file existed; the structuredPatch from the
+                                    // hook lets us emit the real diff for `type: "update"`. The
+                                    // helper returns `{}` if the response shape isn't usable.
+                                    const editDiff = toolUse.name === "Edit" || toolUse.name === "Write"
+                                        ? toolUpdateFromDiffToolResponse(toolResponse)
+                                        : {};
                                     const update = {
                                         _meta: {
                                             claudeCode: {
@@ -1570,7 +2400,32 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                     logger.error(`[claude-agent-acp] Got a tool result for tool use that wasn't tracked: ${chunk.tool_use_id}`);
                     break;
                 }
-                if (toolUse.name !== "TodoWrite") {
+                if (toolUse.name === "TaskCreate" ||
+                    toolUse.name === "TaskUpdate" ||
+                    toolUse.name === "TaskList" ||
+                    toolUse.name === "TaskGet") {
+                    // Headless/SDK sessions emit Task* tools instead of TodoWrite.
+                    // TaskCreate / TaskUpdate mutate the accumulated task list; TaskList
+                    // and TaskGet are read-only so we just suppress their tool_call /
+                    // tool_result events. The plan update is emitted as a snapshot of
+                    // the accumulated state, mirroring the legacy TodoWrite behavior.
+                    const isError = "is_error" in chunk && chunk.is_error;
+                    if (!isError) {
+                        if (toolUse.name === "TaskCreate") {
+                            applyTaskCreate(taskState, toolUse.input, parseTaskCreateOutput(chunk.content));
+                        }
+                        else if (toolUse.name === "TaskUpdate") {
+                            applyTaskUpdate(taskState, toolUse.input);
+                        }
+                    }
+                    if (!isError && (toolUse.name === "TaskCreate" || toolUse.name === "TaskUpdate")) {
+                        update = {
+                            sessionUpdate: "plan",
+                            entries: taskStateToPlanEntries(taskState),
+                        };
+                    }
+                }
+                else if (toolUse.name !== "TodoWrite") {
                     const { _meta: toolMeta, ...toolUpdate } = toolUpdateFromToolResult(chunk, toolUseCache[chunk.tool_use_id], supportsTerminalOutput);
                     // When terminal output is supported, send terminal_output as a
                     // separate notification to match codex-acp's streaming lifecycle:
@@ -1617,6 +2472,7 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
             case "container_upload":
             case "compaction":
             case "compaction_delta":
+            case "advisor_tool_result":
                 break;
             default:
                 unreachable(chunk, logger);
@@ -1645,14 +2501,20 @@ export function streamEventToAcpNotifications(message, sessionId, toolUseCache,
                 clientCapabilities: options?.clientCapabilities,
                 parentToolUseId: message.parent_tool_use_id,
                 cwd: options?.cwd,
+                taskState: options?.taskState,
             });
         case "content_block_delta":
             return toAcpNotifications([event.delta], "assistant", sessionId, toolUseCache, client, logger, {
                 clientCapabilities: options?.clientCapabilities,
                 parentToolUseId: message.parent_tool_use_id,
                 cwd: options?.cwd,
+                taskState: options?.taskState,
             });
-        // No content
+        // No content. `ping` is a Messages-API keep-alive event that the SDK's
+        // `BetaRawMessageStreamEvent` union doesn't include even though the
+        // wire format emits it; the `as never` cast lets us no-op it here
+        // instead of letting it fall through to `unreachable`.
+        case "ping":
         case "message_start":
         case "message_delta":
         case "message_stop":
@@ -1667,7 +2529,12 @@ export function runAcp() {
     const input = nodeToWebWritable(process.stdout);
     const output = nodeToWebReadable(process.stdin);
     const stream = ndJsonStream(input, output);
-    new AgentSideConnection((client) => new ClaudeAcpAgent(client), stream);
+    let agent;
+    const connection = new AgentSideConnection((client) => {
+        agent = new ClaudeAcpAgent(client);
+        return agent;
+    }, stream);
+    return { connection, agent };
 }
 function commonPrefixLength(a, b) {
     let i = 0;
@@ -1676,6 +2543,30 @@ function commonPrefixLength(a, b) {
     }
     return i;
 }
+/** Best-effort first guess of a model's context window from its ID, used only
+ *  until a `result` message arrives with the authoritative `modelUsage` value.
+ *  Anthropic 1M-context variants encode "1m" as a distinct token in the SDK
+ *  model ID (e.g., "claude-opus-4-6-1m"), which `\b1m\b` catches without also
+ *  matching things like "10m" or embedded substrings. */
+function inferContextWindowFromModel(model) {
+    if (/\b1m\b/i.test(model))
+        return 1_000_000;
+    return null;
+}
+function parseModelConfig(raw) {
+    if (!raw)
+        return undefined;
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error("CLAUDE_MODEL_CONFIG must be a JSON object");
+    }
+    const result = {};
+    if (parsed.modelOverrides !== undefined)
+        result.modelOverrides = parsed.modelOverrides;
+    if (parsed.availableModels !== undefined)
+        result.availableModels = parsed.availableModels;
+    return Object.keys(result).length > 0 ? result : undefined;
+}
 function getMatchingModelUsage(modelUsage, currentModel) {
     let bestKey = null;
     let bestLen = 0;