@nodetool-ai/runtime 0.7.0-rc.23 → 0.8.1

package/dist/providers/claude-agent-provider.js

@@ -1,601 +1,1181 @@
 /**
- * Claude Agent Provider
+ * ClaudeAgentProvider — Claude reached through the official
+ * `@anthropic-ai/claude-agent-sdk` instead of an API key.
  *
- * Uses the Claude Agent SDK (@anthropic-ai/claude-agent-sdk) to interact with
- * Claude through the user's Claude subscription (Claude Pro/Max/Team).
+ * Unlike {@link AnthropicProvider}, this provider sends no `ANTHROPIC_API_KEY`:
+ * the SDK drives the bundled `claude` binary (shipped as an optional platform
+ * dependency, so there is nothing to install on PATH) and lets it authenticate
+ * with the machine's logged-in Claude subscription (the credentials stored
+ * under `~/.claude`). The SDK streams `SDKMessage`s, which we translate into the
+ * cross-provider {@link ProviderStreamItem} stream.
  *
- * Requirements:
- * - Claude Code CLI installed and authenticated (`claude` command available)
- * - Active Claude subscription
- * - @anthropic-ai/claude-agent-sdk package installed
+ * `@anthropic-ai/claude-agent-sdk` is a *soft* (optional peer) dependency: it is
+ * not installed by default and must be added with the package manager before
+ * this provider can run. It is loaded lazily via {@link loadSdk}, so a missing
+ * package surfaces as a clear install hint only when the provider is actually
+ * used — the rest of the runtime, and the browser worker bundle, never need it.
  *
- * This provider does NOT require an ANTHROPIC_API_KEY — it uses the Claude Code
- * session which authenticates through the user's Claude subscription.
+ * It is a *pure LLM* provider: the agentic tool loop is collapsed to a single
+ * turn with every built-in tool disabled (`allowedTools: []`), filesystem
+ * settings/skills disabled (`settingSources: []`), permission prompts neutered
+ * (`permissionMode: "dontAsk"`), and the default agent system prompt fully
+ * replaced (`systemPrompt`), so the model behaves like a plain chat completion —
+ * text in, text (and thinking) out.
  *
- * Tool support: tools are exposed as an in-process MCP server via the SDK's
- * createSdkMcpServer() + tool() helpers. Claude calls tools natively through
- * the MCP protocol; the provider yields ToolCall items for tracking.
- * An onToolCall callback must be supplied for tool execution.
+ * Session continuity: when a `threadId` is supplied the provider routes the
+ * thread through a single upstream session and, on subsequent turns, resumes it
+ * (`options.resume`) and sends only the new user delta. The continuation token
+ * ({@link ProviderSession}) is surfaced as a {@link ProviderSessionUpdate} and
+ * persisted by the chat layer onto the assistant message; the in-memory map
+ * below is only a within-process cache (the DB column is authoritative).
  */
-import { BaseProvider } from "./base-provider.js";
-import { createLogger } from "@nodetool-ai/config";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { createLogger, importOptionalModule } from "@nodetool-ai/config";
 import { z } from "zod";
-const log = createLogger("nodetool.runtime.providers.claude_agent");
-const MCP_SERVER_NAME = "nodetool-tools";
+import { BaseProvider, budgetStopItem, resolveTurnBudget } from "./base-provider.js";
+import { sdkNativeReplacements } from "./core-tools.js";
+import { isProviderMessageEvent, isProviderSessionUpdate, isProviderStop } from "./types.js";
+import { hashSystemPrompt } from "./provider-session.js";
+import { PROVIDER_IDS, isFiniteNumber, isNonEmptyString, isObjectLike, isString } from "@nodetool-ai/protocol";
+const log = createLogger("nodetool.runtime.providers.claude-agent");
+/** Replacement system prompt used when the caller supplies none. */
+const DEFAULT_SYSTEM_PROMPT = "You are a helpful assistant.";
 /**
- * Error thrown by the Claude Agent provider. Carries a categorised `kind`
- * alongside a user-facing message so callers (UI, CLI) can decide how to
- * render the failure (e.g. show a "Sign in" button for `auth`).
+ * The Claude Agent SDK's built-in tools. Passed as `disallowedTools` on the
+ * tool-free path so a "pure LLM" completion cannot execute host tools (Bash,
+ * file, web) under bypassPermissions.
  */
-export class ClaudeAgentError extends Error {
-    kind;
-    constructor(kind, message, cause) {
-        super(message, cause !== undefined ? { cause } : undefined);
-        this.name = "ClaudeAgentError";
-        this.kind = kind;
-    }
-}
+const SDK_BUILTIN_TOOLS = [
+    "Bash",
+    "BashOutput",
+    "KillShell",
+    "Read",
+    "Write",
+    "Edit",
+    "MultiEdit",
+    "NotebookEdit",
+    "Glob",
+    "Grep",
+    "WebFetch",
+    "WebSearch",
+    "Task",
+    "TodoWrite"
+];
 /**
- * Classify a raw error from the Claude Agent SDK (or its child process) into
- * a ClaudeAgentError with an actionable, user-facing message.
+ * Env vars a nested Claude subscription session leaks into its children. The
+ * SDK spawns the bundled CLI as a subprocess; left in place these would make it
+ * believe it is itself nested. We strip them via `options.env` rather than any
+ * raw `child_process` plumbing.
  */
-export function classifyClaudeAgentError(error) {
-    if (error instanceof ClaudeAgentError)
-        return error;
-    const original = error instanceof Error ? error.message : String(error);
-    const lower = original.toLowerCase();
-    // SDK package itself not installed (optional dependency missing).
-    if (lower.includes("cannot find module") &&
-        lower.includes("claude-agent-sdk")) {
-        return new ClaudeAgentError("sdk_not_installed", "The @anthropic-ai/claude-agent-sdk package is not installed. " +
-            "The Claude Agent provider requires this optional dependency — install it with " +
-            "`npm install @anthropic-ai/claude-agent-sdk`, then restart NodeTool. " +
-            `Original error: ${original}`, error);
-    }
-    // Claude Code CLI binary not on PATH.
-    if (lower.includes("enoent") ||
-        lower.includes("claude: not found") ||
-        lower.includes("command not found: claude") ||
-        (lower.includes("spawn") && lower.includes("claude"))) {
-        return new ClaudeAgentError("cli_not_found", "Claude Code CLI not found on PATH. The Claude Agent provider spawns the " +
-            "`claude` command — install it from https://docs.anthropic.com/claude-code/install " +
-            "(or via `npm install -g @anthropic-ai/claude-code`), then run `claude login` to " +
-            `authenticate. Original error: ${original}`, error);
-    }
-    // Running as root — SDK refuses --dangerously-skip-permissions.
-    if (lower.includes("dangerously-skip-permissions") ||
-        (lower.includes("root") && lower.includes("refus")) ||
-        (lower.includes("uid") && lower.includes("0"))) {
-        return new ClaudeAgentError("running_as_root", "The Claude Agent SDK refuses to run as root (uid=0) because it passes " +
-            "--dangerously-skip-permissions to the Claude CLI. Run NodeTool as a non-root " +
-            "user, or switch to the `anthropic` provider which uses ANTHROPIC_API_KEY " +
-            `directly. Original error: ${original}`, error);
-    }
-    // Abort.
-    if (lower.includes("abort") ||
-        error instanceof Error && error.name === "AbortError") {
-        return new ClaudeAgentError("aborted", "Claude Agent request was aborted.", error);
-    }
-    // Authentication failure.
-    if (lower.includes("unauthorized") ||
-        lower.includes("401") ||
-        lower.includes("403") ||
-        lower.includes("forbidden") ||
-        lower.includes("not logged in") ||
-        lower.includes("not authenticated") ||
-        lower.includes("invalid api key") ||
-        lower.includes("authentication") ||
-        lower.includes("oauth")) {
-        return new ClaudeAgentError("auth", "Claude Agent authentication failed. Run `claude login` in a terminal to " +
-            "sign in with your Claude subscription, or set ANTHROPIC_API_KEY. " +
-            `Original error: ${original}`, error);
-    }
-    // Rate limit.
-    if (lower.includes("429") ||
-        lower.includes("rate limit") ||
-        lower.includes("too many requests") ||
-        lower.includes("quota")) {
-        return new ClaudeAgentError("rate_limit", "Claude Agent rate limit reached. Wait a moment and retry, or check your " +
-            `Claude subscription usage limits. Original error: ${original}`, error);
-    }
-    // Context length.
-    if (lower.includes("context length") ||
-        lower.includes("context window") ||
-        lower.includes("token limit") ||
-        lower.includes("maximum context") ||
-        lower.includes("too long") ||
-        lower.includes("prompt is too long")) {
-        return new ClaudeAgentError("context_length", "Claude Agent request exceeded the model's context window. Shorten the " +
-            "conversation (clear older messages) or switch to a model with a larger " +
-            `context window. Original error: ${original}`, error);
-    }
-    // Invalid / unknown model.
-    if (lower.includes("model") &&
-        (lower.includes("invalid") ||
-            lower.includes("not found") ||
-            lower.includes("unknown") ||
-            lower.includes("does not exist"))) {
-        return new ClaudeAgentError("invalid_model", "Claude Agent could not use the requested model. Check that the model ID " +
-            "is valid and available on your Claude subscription. " +
-            `Original error: ${original}`, error);
-    }
-    return new ClaudeAgentError("unknown", `Claude Agent provider error: ${original}`, error);
-}
-const CLAUDE_AGENT_MODELS = [
-    {
-        id: "claude-opus-4-7",
-        name: "Claude Opus 4.7",
-        provider: "claude_agent"
-    },
-    {
-        id: "claude-sonnet-4-6",
-        name: "Claude Sonnet 4.6",
-        provider: "claude_agent"
-    },
-    {
-        id: "claude-haiku-4-5",
-        name: "Claude Haiku 4.5",
-        provider: "claude_agent"
-    }
-];
-const DISALLOWED_TOOLS = [];
-function extractText(content) {
-    if (typeof content === "string")
-        return content;
-    if (Array.isArray(content)) {
-        return content
-            .filter((c) => c.type === "text")
-            .map((c) => c.text)
-            .join("\n");
-    }
-    return String(content ?? "");
-}
+const NESTED_SESSION_ENV = /^(CLAUDECODE|CLAUDE_(CODE|SESSION|ENABLE|AFTER|AUTO)_[A-Za-z0-9_]*)$/;
+/** MCP server name under which NodeTool's tools are exposed to the SDK. */
+const TOOL_SERVER_NAME = "nodetool_tools";
+const TOOL_PREFIX = `mcp__${TOOL_SERVER_NAME}__`;
 /**
- * Convert a JSON Schema property to a Zod type.
- * Handles the common subset used by agent tools.
+ * The member expression the retired guest toolbelt was called through:
+ * `await tools.<name>({…})`. Models trained on it still emit it verbatim as a
+ * tool name, so it is stripped on the way in. Nothing produces it any more.
  */
-function jsonSchemaPropertyToZod(prop, z) {
-    const type = prop.type;
-    const enumValues = prop.enum;
-    if (enumValues && Array.isArray(enumValues)) {
-        // z.enum requires string literals
-        if (enumValues.every((v) => typeof v === "string")) {
-            return z.enum(enumValues);
-        }
-        return z.any();
-    }
-    switch (type) {
-        case "string":
-            return z.string();
-        case "number":
-        case "integer":
-            return z.number();
-        case "boolean":
-            return z.boolean();
-        case "array": {
-            const items = prop.items;
-            if (items) {
-                return z.array(jsonSchemaPropertyToZod(items, z));
-            }
-            return z.array(z.any());
-        }
-        case "object": {
-            const properties = prop.properties;
-            if (properties) {
-                const shape = {};
-                const required = prop.required ?? [];
-                for (const [key, val] of Object.entries(properties)) {
-                    let zodType = jsonSchemaPropertyToZod(val, z);
-                    if (!required.includes(key)) {
-                        zodType = zodType.optional();
-                    }
-                    shape[key] = zodType;
-                }
-                return z.object(shape);
-            }
-            return z.record(z.string(), z.any());
-        }
-        default:
-            return z.any();
-    }
-}
+const GUEST_TOOL_PREFIX = "tools.";
+/** Default cap on internal agent turns when tools are in play. */
+const DEFAULT_TOOL_TURNS = 16;
+/** Name of the local plugin the user's DB skills are materialized into. */
+const SKILLS_PLUGIN_NAME = "nodetool-user-skills";
 /**
- * Convert a ProviderTool's JSON Schema inputSchema to a Zod raw shape
- * suitable for the SDK's tool() function.
+ * Lazily import the optional `@anthropic-ai/claude-agent-sdk`. The SDK is a soft
+ * (peer) dependency — it is not bundled with the app and must be installed at
+ * runtime from the Package Manager (Software → Claude Agent SDK), which drops it
+ * into the user-managed optional-node `node_modules`. {@link importOptionalModule}
+ * hides the specifier from bundlers (so the browser/worker bundle never pulls in
+ * the Node-only SDK) and falls back to resolving it from that optional root via
+ * `NODETOOL_OPTIONAL_NODE_MODULES`, so a plain ESM `import` (which ignores
+ * NODE_PATH) still finds a Package-Manager install. A missing package surfaces
+ * as a clear, actionable error at call time.
  */
-function jsonSchemaToZodShape(schema, z) {
-    if (!schema)
-        return {};
-    const properties = schema.properties;
-    if (!properties)
-        return {};
-    const required = schema.required ?? [];
-    const shape = {};
-    for (const [key, prop] of Object.entries(properties)) {
-        let zodType = jsonSchemaPropertyToZod(prop, z);
-        if (!required.includes(key)) {
-            zodType = zodType.optional();
-        }
-        if (typeof prop.description === "string") {
-            zodType = zodType.describe(prop.description);
-        }
-        shape[key] = zodType;
+async function loadSdk() {
+    try {
+        return await importOptionalModule("@anthropic-ai/claude-agent-sdk");
+    }
+    catch (err) {
+        throw new Error("The Claude Agent provider requires the optional " +
+            "'@anthropic-ai/claude-agent-sdk' package, which is not installed. " +
+            "Install it from the Package Manager (Software → Claude Agent SDK).", { cause: err });
     }
-    return shape;
 }
 export class ClaudeAgentProvider extends BaseProvider {
+    /** The SDK runs with bypassPermissions, so its built-in `WebSearch` is live. */
+    get supportsNativeWebSearch() {
+        return true;
+    }
     static requiredSecrets() {
+        // Auth lives in the SDK's own credential store (~/.claude), not in an env
+        // secret — there is nothing for the registry to resolve.
         return [];
     }
+    injectedQueryFn;
+    injectedCreateMcpServerFn;
     /**
-     * Maps threadId → Claude SDK session ID.
-     * Allows resuming conversations across multiple generateMessages() calls.
+     * Within-process cache of the active session per thread. The persisted
+     * `provider_session` column is the source of truth; this only spares a DB
+     * round-trip for back-to-back turns in the same process.
      */
-    _sessions = new Map();
-    constructor(_secrets = {}) {
-        super("claude_agent");
+    sessions = new Map();
+    constructor(_secrets = {}, options = {}) {
+        super(PROVIDER_IDS.CLAUDE_AGENT_SDK);
+        this.injectedQueryFn = options.queryFn ?? null;
+        this.injectedCreateMcpServerFn = options.createMcpServerFn ?? null;
+    }
+    /** The subscription token is the SDK's business — never hand it to a sandbox. */
+    getContainerEnv() {
+        return {};
     }
-    async hasToolSupport(_model) {
+    /**
+     * Tools run inside the SDK's own agent loop ({@link generateLoop}): NodeTool's
+     * tools are exposed as an in-process MCP server whose handlers call back into
+     * the harness's tool executor. The single-turn {@link generateMessages} stays
+     * tool-free.
+     */
+    async hasToolSupport() {
         return true;
     }
+    /**
+     * Stable model aliases the SDK resolves to the latest dated model. Aliases
+     * avoid pinning a version that ages out; the concrete model id the SDK
+     * selects is captured from the stream for accurate cost attribution.
+     */
     async getAvailableLanguageModels() {
-        return CLAUDE_AGENT_MODELS;
+        const provider = PROVIDER_IDS.CLAUDE_AGENT_SDK;
+        return [
+            { id: "fable", name: "Claude Fable (subscription)", provider },
+            { id: "opus", name: "Claude Opus (subscription)", provider },
+            { id: "sonnet", name: "Claude Sonnet (subscription)", provider },
+            { id: "haiku", name: "Claude Haiku (subscription)", provider }
+        ];
+    }
+    /** Resolve the SDK `query`, lazily importing it off the Node-only package. */
+    async loadQuery() {
+        if (this.injectedQueryFn)
+            return this.injectedQueryFn;
+        const mod = await loadSdk();
+        return mod.query;
+    }
+    /** Resolve the SDK `createSdkMcpServer`, lazily importing the Node-only pkg. */
+    async loadCreateMcpServer() {
+        if (this.injectedCreateMcpServerFn)
+            return this.injectedCreateMcpServerFn;
+        const mod = await loadSdk();
+        // SAFETY: the SDK's factory is generic over each tool's Zod shape; this
+        // provider always hands it the default `AnyZodRawShape` definitions.
+        return mod.createSdkMcpServer;
     }
     /**
-     * Extract the system prompt and the last user message from the messages array.
+     * Run the SDK's own agent loop. Tool-free turns behave exactly like
+     * {@link generateMessages}; with `tools` we expose them as an in-process MCP
+     * server whose handlers call `executeTool`, let the SDK loop (`maxTurns > 1`),
+     * and translate its `tool_use`/`tool_result` stream into ToolCall items and
+     * persistable {@link ProviderMessageEvent}s.
      */
-    extractPrompt(messages) {
-        let systemPrompt = "You are a helpful assistant.";
-        let prompt = "";
-        for (const msg of messages) {
-            if (msg.role === "system") {
-                systemPrompt = extractText(msg.content);
+    async *generateLoop(args) {
+        // The SDK owns the loop, so honoring the budget is this override's job:
+        // reserve before the first turn, and again after every assistant turn that
+        // requested tools — that is the point where the SDK will make another call.
+        // A refusal aborts the session instead of letting it spend past the cap.
+        const { runBudget, turnBudget } = resolveTurnBudget(args.turnBudget);
+        if (runBudget?.deadline.expired()) {
+            yield budgetStopItem(runBudget);
+            return;
+        }
+        // Every turn this session makes holds its own reservation, and the whole
+        // set is settled in the `finally` below — the SDK reports one number for
+        // the session, not one per turn.
+        const reservations = [];
+        if (turnBudget) {
+            const first = this._admitTurn(turnBudget, args.model, args.messages);
+            if (first === null) {
+                yield budgetStopItem(runBudget);
+                return;
             }
+            reservations.push(first);
+        }
+        // Drop every NodeTool tool the SDK ships a built-in for. Those built-ins
+        // are live under bypassPermissions, so keeping the MCP copy would give one
+        // capability two surfaces and make the model pick between them.
+        const offered = args.tools ?? [];
+        const replaced = sdkNativeReplacements(offered.map((t) => t.name), args.workspaceDir);
+        const tools = offered.filter((t) => !replaced.has(t.name));
+        if (replaced.size > 0) {
+            log.debug("Using SDK built-ins in place of NodeTool tools", {
+                replaced: [...replaced]
+            });
         }
-        // Walk backwards to find the last user message — that's our prompt.
-        for (let i = messages.length - 1; i >= 0; i--) {
-            if (messages[i].role === "user") {
-                prompt = extractText(messages[i].content);
-                break;
+        const executeTool = args.executeTool;
+        // A tool dispatches either through its own `execute` or the harness
+        // `executeTool`; build the MCP server when at least one route exists.
+        const hasToolExecute = tools.some((t) => t.execute);
+        // The SDK loop is stopped by aborting this controller — a terminal tool
+        // fires it after running. Bridge the caller's signal into it too, and pass
+        // its signal (overriding args.signal) down so runTurn cancels on either.
+        const abortController = new AbortController();
+        const onExternalAbort = () => abortController.abort();
+        if (args.signal) {
+            if (args.signal.aborted)
+                abortController.abort();
+            else
+                args.signal.addEventListener("abort", onExternalAbort, { once: true });
+        }
+        let mcp = null;
+        if (tools.length > 0 && (executeTool || hasToolExecute)) {
+            const createServer = await this.loadCreateMcpServer();
+            // MCP tool results carry typed content blocks, so image-bearing results
+            // (view_image) are returned as real image blocks the SDK hands to Claude —
+            // no flattening to text on the agent-SDK path.
+            const defs = tools.map((t) => toolDefinition(t, async (name, toolArgs) => {
+                // The SDK runs parallel calls of one tool in the same millisecond,
+                // so a clock alone would hand them one id.
+                const toolCallId = `call_${name}_${crypto.randomUUID()}`;
+                const result = t.execute
+                    ? await t.execute(toolArgs, toolCallId)
+                    : executeTool
+                        ? await executeTool({
+                            id: toolCallId,
+                            name,
+                            args: toolArgs
+                        })
+                        : `Tool "${name}" is not available`;
+                // A terminal tool ends the SDK loop after its result is delivered.
+                if (t.terminal)
+                    abortController.abort();
+                return result;
+            }, args.resolveMedia));
+            const server = createServer({
+                name: TOOL_SERVER_NAME,
+                version: "1.0.0",
+                tools: defs
+            });
+            mcp = {
+                mcpServers: { [TOOL_SERVER_NAME]: server },
+                allowedTools: tools.map((t) => `${TOOL_PREFIX}${t.name}`)
+            };
+        }
+        // Materialize the user's skills into a throwaway local plugin the SDK's
+        // native skill loader discovers. Best-effort: a disk failure drops skills
+        // for the turn, it does not sink it. Cleaned up in the `finally` below.
+        let skillsPlugin = null;
+        if ((args.skills?.length ?? 0) > 0) {
+            try {
+                skillsPlugin = await materializeSkillsPlugin(args.skills ?? []);
+            }
+            catch (err) {
+                log.warn("Failed to materialize user skills for the SDK", {
+                    error: err instanceof Error ? err.message : String(err)
+                });
             }
         }
-        if (!prompt) {
-            prompt = "Hello";
+        const costBefore = turnBudget ? this.getTotalCost() : 0;
+        // Set when the budget refuses a further turn: the SDK session is aborted
+        // and the stop is yielded once the stream has drained, so it stays the
+        // loop's final item.
+        let budgetStop = null;
+        try {
+            const stream = this.runWithSession({ ...args, signal: abortController.signal }, {
+                emitMessages: true,
+                // Turns are for tool rounds, and a replaced tool still costs one —
+                // key this on what the caller offered, not on what survived into MCP.
+                maxTurns: offered.length > 0 ? (args.maxIterations ?? DEFAULT_TOOL_TURNS) : 1,
+                mcp,
+                toolsOffered: offered.length > 0,
+                cwd: args.workspaceDir,
+                skillsPlugin
+            });
+            // The SDK grows the conversation internally, so reserving against the
+            // opening prompt every time would under-count every later turn — badly,
+            // on a tool-heavy loop. The messages it emits are the same ones it is
+            // accumulating, so the transcript is rebuilt here to reserve against.
+            const transcript = [...args.messages];
+            for await (const item of stream) {
+                yield item;
+                if (!turnBudget)
+                    continue;
+                if (!isProviderMessageEvent(item))
+                    continue;
+                transcript.push(item.message);
+                const isToolCallingTurn = item.message.role === "assistant" &&
+                    (item.message.toolCalls?.length ?? 0) > 0;
+                if (!isToolCallingTurn)
+                    continue;
+                const next = this._admitTurn(turnBudget, args.model, transcript);
+                if (next === null) {
+                    budgetStop = budgetStopItem(runBudget);
+                    abortController.abort();
+                    continue;
+                }
+                reservations.push(next);
+            }
+        }
+        finally {
+            // The SDK reports usage once, on the terminal `result` message, so a
+            // per-turn actual doesn't exist here. Reservations accumulate untouched
+            // for the session's duration — conservative by construction — and the
+            // real number lands when the session ends.
+            //
+            // Except when it doesn't: an aborted session never emits `result`, so
+            // nothing is recorded even though its turns ran and were billed. That is
+            // the *normal* ending here — a terminal tool (`finish_step`) aborts the
+            // query — so booking zero would mean the cap never counted a single
+            // successful decision on this provider. A zero delta is therefore read
+            // as "unknown", and the reserved worst case is charged instead.
+            if (turnBudget) {
+                const observed = this.getTotalCost() - costBefore;
+                // One number covers the whole session, so it is booked against the
+                // first reservation and the rest settle at zero; with no number at
+                // all, each reservation is charged its own worst case.
+                let remaining = observed > 0 ? observed : null;
+                for (const reservation of reservations) {
+                    turnBudget.commit(reservation, remaining);
+                    if (remaining !== null)
+                        remaining = 0;
+                }
+            }
+            if (args.signal)
+                args.signal.removeEventListener("abort", onExternalAbort);
+            // Remove the throwaway skills plugin. The SDK's subprocess has finished
+            // reading it by now (the stream is drained), so best-effort cleanup is
+            // safe; a leftover temp dir is not worth failing the turn over.
+            if (skillsPlugin) {
+                await fs
+                    .rm(skillsPlugin.dir, { recursive: true, force: true })
+                    .catch(() => { });
+            }
+        }
+        if (budgetStop) {
+            yield budgetStop;
         }
-        return { systemPrompt, prompt };
-    }
-    /** Look up an existing Claude session for the given threadId. */
-    getSessionId(threadId) {
-        if (!threadId)
-            return undefined;
-        return this._sessions.get(threadId);
-    }
-    /** Store the Claude session ID for a threadId. */
-    setSessionId(threadId, sessionId) {
-        this._sessions.set(threadId, sessionId);
     }
-    /** Remove a stored session (e.g. when a conversation is closed). */
-    clearSession(threadId) {
-        this._sessions.delete(threadId);
+    async *generateMessages(args) {
+        // Single-turn, tool-free primitive. The agent loop lives in generateLoop.
+        const resultTool = args.tools?.length === 1 &&
+            args.toolChoice === args.tools[0].name
+            ? args.tools[0]
+            : undefined;
+        const resultSchema = resultTool?.inputSchema;
+        const config = {
+            emitMessages: false,
+            maxTurns: args.maxTurns ?? 1,
+            mcp: null,
+            toolsOffered: false
+        };
+        if (resultTool && resultSchema) {
+            config.outputFormat = { type: "json_schema", schema: resultSchema };
+            config.resultToolName = resultTool.name;
+        }
+        yield* this.runWithSession(args, config);
     }
     /**
-     * Build an in-process MCP server from ProviderTool definitions.
-     * Each tool's handler calls the onToolCall callback.
+     * Shared session machinery for {@link generateMessages} and
+     * {@link generateLoop}: decide resume vs fresh (best-effort, with a
+     * full-history priming fallback), then drive one SDK turn via {@link runTurn}.
+     * `config` selects single-turn streaming vs the tool/message-emitting loop.
      */
-    buildMcpServer(tools, onToolCall, sdk, z, toolCallTracker) {
-        const mcpTools = tools.map((t) => {
-            const zodShape = jsonSchemaToZodShape(t.inputSchema, z);
-            return sdk.tool(t.name, t.description ?? "", zodShape, async (args) => {
-                // Track the tool call for yielding to the caller
-                const toolCall = {
-                    id: `call_${Date.now()}_${toolCallTracker.length}`,
-                    name: t.name,
-                    args
-                };
-                toolCallTracker.push(toolCall);
-                log.debug("MCP tool called", { name: t.name, args });
-                try {
-                    const result = await onToolCall(t.name, args);
-                    return { content: [{ type: "text", text: result }] };
-                }
-                catch (e) {
-                    const errorMsg = `Tool execution error: ${e}`;
-                    log.error("MCP tool error", { name: t.name, error: errorMsg });
-                    return {
-                        content: [{ type: "text", text: errorMsg }],
-                        isError: true
-                    };
-                }
-            });
-        });
-        return sdk.createSdkMcpServer({
-            name: MCP_SERVER_NAME,
-            version: "1.0.0",
-            tools: mcpTools
-        });
-    }
-    async *generateMessages(args) {
-        const toolCount = args.tools?.length ?? 0;
-        const hasOnToolCall = !!args.onToolCall;
-        const hasTools = toolCount > 0 && hasOnToolCall;
-        const { systemPrompt, prompt } = this.extractPrompt(args.messages);
+    async *runWithSession(args, config) {
+        const systemPrompt = extractSystemPrompt(args.messages);
+        const systemHash = hashSystemPrompt(systemPrompt);
         const threadId = args.threadId ?? null;
-        const resumeSessionId = this.getSessionId(threadId);
-        // Pre-flight: fail fast with a clear message if running as root, since the
-        // SDK always refuses --dangerously-skip-permissions for uid=0. Without this
-        // check the underlying error surfaces as an opaque child-process failure.
-        if (typeof process.getuid === "function" && process.getuid() === 0) {
-            throw new ClaudeAgentError("running_as_root", "The Claude Agent SDK refuses to run as root (uid=0) because it passes " +
-                "--dangerously-skip-permissions to the Claude CLI. Run NodeTool as a " +
-                "non-root user, or use the `anthropic` provider with ANTHROPIC_API_KEY.");
-        }
-        log.info("Claude Agent generateMessages called", {
-            toolCount,
-            hasOnToolCall,
-            hasTools,
-            toolNames: args.tools?.map((t) => t.name) ?? []
-        });
-        // Lazy-load the SDK only on first use. This keeps anything that imports
-        // the provider transitively (Electron main, CLI, tests) from requiring
-        // the SDK at startup.
-        let sdk;
-        try {
-            sdk = await import("@anthropic-ai/claude-agent-sdk");
-        }
-        catch (err) {
-            throw classifyClaudeAgentError(err);
-        }
-        // Track tool calls made during this query (populated by MCP handlers)
-        const toolCallTracker = [];
-        // Build MCP server if tools + callback provided
-        let mcpServer;
-        let allowedTools = [];
-        if (hasTools && args.tools && args.onToolCall) {
-            mcpServer = this.buildMcpServer(args.tools, args.onToolCall, sdk, z, toolCallTracker);
-            allowedTools = args.tools.map((t) => `mcp__${MCP_SERVER_NAME}__${t.name}`);
-            log.info("MCP server built", {
-                mcpToolCount: args.tools.length,
-                allowedTools
-            });
+        // Source of truth is the token threaded in from the persisted assistant
+        // message; the in-memory cache is a fallback for same-process turns.
+        const prior = args.providerSession ??
+            (threadId ? (this.sessions.get(threadId) ?? null) : null);
+        const canResume = prior != null &&
+            prior.providerId === this.provider &&
+            prior.model === args.model &&
+            (prior.systemHash == null || prior.systemHash === systemHash) &&
+            args.messages.length > prior.checkpoint;
+        // Cache the session in-process only when the caller doesn't thread a token
+        // in (the CLI path). When it does (the websocket path), the DB is
+        // authoritative and the emitted checkpoint may be relative to a trimmed
+        // view, so caching it would corrupt a later cache-based resume.
+        const cacheSession = args.providerSession == null;
+        // RESUME is best-effort: a session file may have been pruned/expired. If the
+        // resume query fails *before* any content reached the consumer, fall back to
+        // a fresh session; if it fails mid-stream we surface the error instead.
+        const emitted = { content: false };
+        if (canResume && prior) {
+            const delta = buildResumeDelta(args.messages, prior.checkpoint);
+            try {
+                yield* this.runTurn(args, {
+                    prompt: delta,
+                    resume: prior.token,
+                    systemPrompt,
+                    systemHash,
+                    threadId,
+                    emitted,
+                    cacheSession,
+                    config
+                });
+                return;
+            }
+            catch (err) {
+                if (emitted.content)
+                    throw err;
+                log.warn("Claude session resume failed; starting fresh", {
+                    error: err instanceof Error ? err.message : String(err)
+                });
+            }
         }
-        log.info("Claude Agent request", {
-            model: args.model,
-            promptLength: prompt.length,
+        // Fresh / fallback. When the caller handed us only the delta (a trimmed
+        // `messages` view) plus a loader, prime from the full conversation so prior
+        // context isn't lost — the session may have expired or the system prompt
+        // changed. Otherwise `messages` already holds the full history.
+        const freshMessages = args.loadFullHistory
+            ? await args.loadFullHistory()
+            : args.messages;
+        yield* this.runTurn(args, {
+            prompt: buildFreshPrompt(freshMessages),
+            resume: undefined,
+            systemPrompt,
+            systemHash,
             threadId,
-            resuming: !!resumeSessionId,
-            tools: hasTools ? args.tools.map((t) => t.name) : [],
-            mcpEnabled: !!mcpServer
+            emitted,
+            cacheSession,
+            config
         });
-        // Strip all Claude Code env vars to allow running inside a Claude Code session.
-        // Just deleting CLAUDECODE/CLAUDE_CODE is not enough — the SDK inherits
-        // session IDs, proxy settings, auth tokens, etc. that conflict with
-        // spawning a nested Claude Code process.
-        const cleanEnv = { ...process.env };
-        for (const key of Object.keys(cleanEnv)) {
-            if (key === "CLAUDECODE" ||
-                key === "CLAUDE_CODE" ||
-                key.startsWith("CLAUDE_CODE_") ||
-                key.startsWith("CLAUDE_SESSION_") ||
-                key.startsWith("CLAUDE_ENABLE_") ||
-                key.startsWith("CLAUDE_AFTER_") ||
-                key.startsWith("CLAUDE_AUTO_")) {
-                delete cleanEnv[key];
-            }
-        }
-        // Bridge AbortSignal → AbortController for the SDK
-        let abortController;
+    }
+    /** Drive one SDK `query` turn and translate its messages into stream items. */
+    async *runTurn(args, plan) {
+        const queryFn = await this.loadQuery();
+        // Cancellation: the SDK stops the underlying query when its AbortController
+        // fires. Bridge the caller's signal onto a fresh controller per turn.
+        const abortController = new AbortController();
+        const onAbort = () => abortController.abort();
         if (args.signal) {
-            abortController = new AbortController();
-            if (args.signal.aborted) {
+            if (args.signal.aborted)
                 abortController.abort();
-            }
-            else {
-                args.signal.addEventListener("abort", () => abortController.abort(), { once: true });
-            }
+            else
+                args.signal.addEventListener("abort", onAbort, { once: true });
         }
-        let queryHandle;
-        try {
-            queryHandle = sdk.query({
-                prompt,
-                options: {
-                    model: args.model,
-                    systemPrompt,
-                    maxTurns: hasTools ? (args.maxTurns ?? 100) : 1,
-                    permissionMode: "bypassPermissions",
-                    allowDangerouslySkipPermissions: true,
-                    disallowedTools: DISALLOWED_TOOLS,
-                    allowedTools,
-                    // Isolate from the host's Claude Code config: don't load
-                    // user/project/local settings (which is where installed skills
-                    // and plugin configs live), and pass an empty plugin list so
-                    // no plugin commands/agents/hooks are registered.
-                    settingSources: [],
-                    plugins: [],
-                    env: cleanEnv,
-                    ...(abortController ? { abortController } : {}),
-                    ...(mcpServer
-                        ? { mcpServers: { [MCP_SERVER_NAME]: mcpServer } }
-                        : {}),
-                    ...(resumeSessionId ? { resume: resumeSessionId } : {})
+        const options = {
+            systemPrompt: plan.systemPrompt,
+            // Pass aliases ("sonnet"/"opus"/"haiku") straight through to the SDK.
+            model: args.model || undefined,
+            // 1 for a single turn; higher when tools may drive multiple rounds.
+            maxTurns: plan.config.maxTurns,
+            // Auto-approve NodeTool's MCP tools (this is the no-prompt allowlist, not
+            // an availability restriction). Empty (pure LLM) when tool-free.
+            allowedTools: plan.config.mcp?.allowedTools ?? [],
+            // Do NOT load repo .claude / CLAUDE.md / skills.
+            settingSources: [],
+            // Run without asking for permissions: never prompt AND never deny. This
+            // lets the SDK agent use its built-in tools (WebSearch/WebFetch/Bash/…)
+            // alongside NodeTool's MCP tools. bypassPermissions requires the explicit
+            // safety flag below.
+            permissionMode: "bypassPermissions",
+            allowDangerouslySkipPermissions: true,
+            // On the tool-free path (the documented "pure LLM" primitive used by
+            // generateMessage/generateMessages), explicitly disable the SDK's
+            // built-in tools. Under bypassPermissions they are otherwise live and
+            // auto-approved, so a prompt-injected "call Bash …" in untrusted text
+            // being summarized/classified would execute on the host. allowedTools is
+            // only a no-prompt approval list, not an availability restriction.
+            //
+            // The test is `toolsOffered`, not `mcp`: a caller whose every tool was
+            // replaced by a built-in offered tools and has no MCP server, and
+            // disabling the built-ins there would leave it with nothing.
+            //
+            // `ToolSearch` is disabled on BOTH paths. It searches tools the SDK has
+            // deferred, and NodeTool defers none — it registers its handful of tools
+            // in-process — so the search always comes back empty. A model that fell
+            // back to it after a mis-named tool call got nothing and stalled the turn.
+            disallowedTools: plan.config.toolsOffered
+                ? ["ToolSearch"]
+                : [...SDK_BUILTIN_TOOLS, "ToolSearch"],
+            includePartialMessages: true,
+            // Setting env REPLACES the child env, so spread process.env minus the
+            // nested-session leakage. Preserves PATH/HOME/ANTHROPIC_BASE_URL/proxies.
+            env: buildChildEnv(),
+            abortController
+        };
+        if (plan.config.outputFormat) {
+            options.outputFormat = plan.config.outputFormat;
+        }
+        // Anchor the path-scoped built-ins to the run's workspace, which is where
+        // the NodeTool tools they replace were contained.
+        if (plan.config.cwd) {
+            options.cwd = plan.config.cwd;
+        }
+        if (plan.config.mcp) {
+            options.mcpServers = plan.config.mcp.mcpServers;
+        }
+        // Enable the SDK's native skill loop over the user's DB skills, which were
+        // materialized into an isolated local plugin. This rides `plugins`, NOT
+        // `settingSources` (kept `[]`), so no `~/.claude` / `.claude` settings or
+        // `CLAUDE.md` are read; `skipMcpDiscovery` blocks any `.mcp.json` the dir
+        // might carry. `skills` names the exact user skills to enable, so any
+        // bundled skill is hidden from the listing and the `Skill` tool.
+        if (plan.config.skillsPlugin) {
+            options.plugins = [
+                {
+                    type: "local",
+                    path: plan.config.skillsPlugin.dir,
+                    skipMcpDiscovery: true
                 }
-            });
+            ];
+            options.skills = plan.config.skillsPlugin.names;
         }
-        catch (err) {
-            const classified = classifyClaudeAgentError(err);
-            log.error("Claude Agent sdk.query() failed", {
-                kind: classified.kind,
-                error: classified.message,
-                model: args.model
-            });
-            throw classified;
+        if (plan.resume) {
+            options.resume = plan.resume;
         }
-        // streamedTextLength tracks the text position within the current assistant turn.
-        // It resets when a new turn begins (after tool execution in multi-turn MCP queries).
-        let streamedTextLength = 0;
-        let yieldedToolCallCount = 0;
-        // Track whether we already yielded text via stream_event/assistant messages
-        // so we can skip the duplicate result event.
-        let hasYieldedText = false;
+        // Log the exact wire body (sans the non-serializable AbortController, MCP
+        // server instances, and the full env, which can carry secrets) so the
+        // request-log UI shows what was sent without leaking the environment.
+        this.recordRequestPayload({
+            prompt: plan.prompt,
+            resume: plan.resume ?? null,
+            options: {
+                ...options,
+                abortController: undefined,
+                env: undefined,
+                mcpServers: plan.config.mcp
+                    ? Object.keys(plan.config.mcp.mcpServers ?? {})
+                    : undefined
+            }
+        });
+        log.debug("Claude Agent SDK request", {
+            model: args.model,
+            resume: Boolean(plan.resume)
+        });
+        let resolvedModel = args.model;
+        // When partial deltas stream, we render from them and skip the final
+        // assistant message to avoid duplication; if a build omits partials we fall
+        // back to the final message's content blocks.
+        let streamedFromPartials = false;
+        // The SDK splits one API assistant turn into one frame per content block —
+        // thinking, then text, then each tool_use. Emitting a message per frame
+        // would hand the consumer a text-only assistant message in the middle of a
+        // tool round, which every chat surface reads as "the turn ended" (the chat
+        // UI flips the composer back to Send and hides Stop), and would write an
+        // empty row for a thinking-only frame. Buffer the blocks and emit one
+        // message per assistant turn, text and tool calls together, the way every
+        // other provider does.
+        let pending = null;
+        const flushPending = () => {
+            const buffered = pending;
+            pending = null;
+            if (!buffered)
+                return null;
+            if (!buffered.text && buffered.toolCalls.length === 0)
+                return null;
+            return {
+                type: "message",
+                message: {
+                    role: "assistant",
+                    content: buffered.text || null,
+                    toolCalls: buffered.toolCalls.length ? buffered.toolCalls : null
+                }
+            };
+        };
         try {
-            for await (const msg of queryHandle) {
-                const msgObj = msg;
-                const msgType = msgObj.type;
-                // Capture session ID from the init event
-                if (msgType === "system" &&
-                    msgObj.subtype === "init" &&
-                    typeof msgObj.session_id === "string" &&
-                    threadId) {
-                    this.setSessionId(threadId, msgObj.session_id);
-                    log.debug("Claude session initialized", {
-                        threadId,
-                        sessionId: msgObj.session_id
-                    });
+            for await (const msg of queryFn({ prompt: plan.prompt, options })) {
+                if (msg.type === "system" && msg.subtype === "init") {
+                    // Capture the session and surface it immediately so a streaming
+                    // consumer can persist it onto the assistant message it creates.
+                    if (isNonEmptyString(msg.model))
+                        resolvedModel = msg.model;
+                    if (plan.threadId) {
+                        const session = {
+                            providerId: this.provider,
+                            model: args.model,
+                            token: msg.session_id,
+                            checkpoint: args.messages.length,
+                            systemHash: plan.systemHash
+                        };
+                        if (plan.cacheSession)
+                            this.sessions.set(plan.threadId, session);
+                        yield { type: "session", session };
+                    }
                     continue;
                 }
-                // Yield any new tool calls that were tracked by MCP handlers.
-                // When tool calls appear, a new assistant turn follows — reset text position.
-                if (yieldedToolCallCount < toolCallTracker.length) {
-                    while (yieldedToolCallCount < toolCallTracker.length) {
-                        yield toolCallTracker[yieldedToolCallCount++];
+                if (msg.type === "stream_event") {
+                    const captured = capturedModelFromPartial(msg);
+                    if (captured)
+                        resolvedModel = captured;
+                    const delta = partialDelta(msg);
+                    if (delta?.text != null) {
+                        streamedFromPartials = true;
+                        plan.emitted.content = true;
+                        yield { type: "chunk", content: delta.text, done: false };
+                    }
+                    else if (delta?.thinking != null) {
+                        streamedFromPartials = true;
+                        plan.emitted.content = true;
+                        yield {
+                            type: "chunk",
+                            content: delta.thinking,
+                            done: false,
+                            thinking: true
+                        };
                     }
-                    // Reset for the next assistant turn's text
-                    streamedTextLength = 0;
+                    continue;
                 }
-                // Stream events provide incremental text updates
-                if (msgType === "stream_event") {
-                    const partial = msgObj.message;
-                    const content = partial?.content;
-                    if (Array.isArray(content)) {
-                        const text = content
-                            .filter((b) => b?.type === "text" && typeof b.text === "string")
-                            .map((b) => b.text)
-                            .join("");
-                        if (text.length > streamedTextLength) {
-                            const delta = text.slice(streamedTextLength);
-                            streamedTextLength = text.length;
-                            hasYieldedText = true;
-                            yield { type: "chunk", content: delta, done: false };
+                if (msg.type === "assistant") {
+                    const m = msg.message;
+                    if (m && isNonEmptyString(m.model))
+                        resolvedModel = m.model;
+                    // Fallback only: no partials arrived, so render text/thinking from the
+                    // final content blocks — kept strictly separate, never merged.
+                    if (!streamedFromPartials) {
+                        for (const block of finalBlocks(msg)) {
+                            plan.emitted.content = true;
+                            yield block.thinking
+                                ? {
+                                    type: "chunk",
+                                    content: block.content,
+                                    done: false,
+                                    thinking: true
+                                }
+                                : { type: "chunk", content: block.content, done: false };
+                        }
+                    }
+                    // The loop needs each assistant turn (text + any tool calls) as a
+                    // persistable message, and a ToolCall item per call for live display.
+                    // The ToolCall items go out immediately; the message waits for the
+                    // rest of the turn's blocks (see `pending`).
+                    if (plan.config.emitMessages) {
+                        const { text, toolCalls } = assistantParts(msg);
+                        for (const tc of toolCalls)
+                            yield tc;
+                        const parentToolUseId = msg.parent_tool_use_id ?? null;
+                        if (pending && pending.parentToolUseId !== parentToolUseId) {
+                            // A subagent's turn and the main agent's are different turns.
+                            const flushed = flushPending();
+                            if (flushed)
+                                yield flushed;
                         }
+                        pending ??= { parentToolUseId, text: "", toolCalls: [] };
+                        pending.text += text;
+                        pending.toolCalls.push(...toolCalls);
                     }
                     continue;
                 }
-                // Full assistant message — emit any remaining text not covered by stream events
-                if (msgType === "assistant") {
-                    const message = msgObj.message;
-                    const content = message?.content;
-                    if (Array.isArray(content)) {
-                        const text = content
-                            .filter((b) => b?.type === "text" && typeof b.text === "string")
-                            .map((b) => b.text)
-                            .join("");
-                        if (text.length > streamedTextLength) {
-                            const delta = text.slice(streamedTextLength);
-                            streamedTextLength = text.length;
-                            hasYieldedText = true;
-                            yield { type: "chunk", content: delta, done: false };
+                // Tool results come back as a user message; surface them as tool
+                // messages so the harness can persist them. The assistant turn that
+                // asked for them is complete by now, so it goes out first.
+                if (msg.type === "user") {
+                    if (plan.config.emitMessages) {
+                        const flushed = flushPending();
+                        if (flushed)
+                            yield flushed;
+                        for (const tr of toolResultsFromUser(msg)) {
+                            yield {
+                                type: "message",
+                                message: {
+                                    role: "tool",
+                                    toolCallId: tr.toolCallId,
+                                    content: tr.content
+                                }
+                            };
                         }
                     }
-                    // Reset for next turn (if multi-turn agentic query)
-                    streamedTextLength = 0;
                     continue;
                 }
-                // Result event — surface errors and fall back text when nothing was streamed.
-                if (msgType === "result") {
-                    const subtype = msgObj.subtype;
-                    const isError = msgObj.is_error === true;
-                    const rawResult = msgObj.result;
-                    const resultText = typeof rawResult === "string" ? rawResult : undefined;
-                    if (isError || (subtype && subtype.startsWith("error"))) {
-                        const detail = resultText ?? this.describeErrorSubtype(subtype);
-                        const kind = subtype === "error_max_turns"
-                            ? "max_turns"
-                            : subtype === "error_during_execution"
-                                ? "execution"
-                                : "unknown";
-                        const message = kind === "max_turns"
-                            ? `Claude Agent stopped after reaching the max turn limit without ` +
-                                `finishing. Increase maxTurns, simplify the task, or break it into ` +
-                                `smaller steps. Detail: ${detail}`
-                            : kind === "execution"
-                                ? `Claude Agent execution error: ${detail}`
-                                : `Claude Agent returned an error result (${subtype ?? "unknown"}): ${detail}`;
-                        log.error("Claude Agent result error", {
-                            subtype,
-                            is_error: isError,
-                            detail
-                        });
-                        throw new ClaudeAgentError(kind, message);
+                if (msg.type === "result") {
+                    // Bill every terminal result, not just the successful ones: an
+                    // errored/max-turns run still consumed (and was charged for) tokens.
+                    this.trackResultUsage(msg, resolvedModel);
+                    if (msg.subtype === "success") {
+                        const flushed = flushPending();
+                        if (flushed)
+                            yield flushed;
+                        const structured = msg.structured_output;
+                        if (plan.config.resultToolName &&
+                            isObjectLike(structured) &&
+                            !Array.isArray(structured)) {
+                            yield {
+                                id: `result_${msg.uuid}`,
+                                name: plan.config.resultToolName,
+                                args: structured
+                            };
+                        }
+                        yield { type: "chunk", content: "", done: true };
                     }
-                    if (!hasYieldedText && resultText && resultText.length > 0) {
-                        yield { type: "chunk", content: resultText, done: false };
+                    else {
+                        throw resultError(msg);
                     }
+                    continue;
                 }
             }
+            // A stream that ended without a terminal `result` still owes its last
+            // assistant turn.
+            const trailing = flushPending();
+            if (trailing)
+                yield trailing;
         }
         catch (err) {
-            const classified = classifyClaudeAgentError(err);
-            log.error("Claude Agent stream failed", {
-                kind: classified.kind,
-                error: classified.message,
-                model: args.model
-            });
-            throw classified;
+            // The query can reject (auth failure, missing session, spawn error). Never
+            // collapse to a generic string — surface the real message.
+            if (args.signal?.aborted)
+                return;
+            throw err instanceof Error ? err : new Error(String(err));
         }
-        // Yield any remaining tool calls
-        while (yieldedToolCallCount < toolCallTracker.length) {
-            yield toolCallTracker[yieldedToolCallCount++];
+        finally {
+            // Terminate the SDK query on every exit path. On normal completion the
+            // query has already finished and this is a no-op; on an early `break`
+            // (consumer cancelled) or a throw it is the only thing that stops the
+            // subprocess, which otherwise runs its whole agentic loop to completion.
+            abortController.abort();
+            if (args.signal)
+                args.signal.removeEventListener("abort", onAbort);
         }
-        // Final done signal
-        yield { type: "chunk", content: "", done: true };
+    }
+    /** Record token usage from a terminal `result` message (success or error). */
+    trackResultUsage(msg, model) {
+        const usage = msg.usage;
+        if (!usage)
+            return;
+        const input = num(usage.input_tokens);
+        const cacheRead = num(usage.cache_read_input_tokens);
+        const cacheWrite = num(usage.cache_creation_input_tokens);
+        // genai-prices expects the full prompt total (uncached + cache read/write),
+        // matching AnthropicProvider's accounting.
+        this.trackUsage(model, {
+            inputTokens: input + cacheRead + cacheWrite,
+            outputTokens: num(usage.output_tokens),
+            cachedTokens: cacheRead,
+            cacheWriteTokens: cacheWrite
+        });
     }
     async generateMessage(args) {
-        const parts = [];
+        let content = "";
         const toolCalls = [];
         for await (const item of this.generateMessages(args)) {
-            if ("type" in item && item.type === "chunk") {
-                const chunk = item;
-                if (chunk.content)
-                    parts.push(chunk.content);
-            }
-            if ("id" in item && "name" in item && "args" in item) {
+            if (isProviderSessionUpdate(item) ||
+                isProviderMessageEvent(item) ||
+                isProviderStop(item))
+                continue;
+            if ("args" in item) {
                 toolCalls.push(item);
             }
+            else if (!item.thinking && isString(item.content)) {
+                content += item.content;
+            }
         }
         return {
             role: "assistant",
-            content: parts.join(""),
-            ...(toolCalls.length > 0 ? { toolCalls } : {})
+            content: content || null,
+            toolCalls: toolCalls.length ? toolCalls : null
         };
     }
-    describeErrorSubtype(subtype) {
-        switch (subtype) {
-            case "error_max_turns":
-                return "agent reached the maximum number of turns";
-            case "error_during_execution":
-                return "an error occurred during agent execution";
-            default:
-                return subtype ?? "unknown error";
+}
+function num(value) {
+    return isFiniteNumber(value) ? value : 0;
+}
+/**
+ * `CLAUDE_CODE_OAUTH_TOKEN` matches {@link NESTED_SESSION_ENV} but is the CLI's
+ * credential, not session leakage: on a headless host (CI) with no interactive
+ * `~/.claude` login it is the *only* way the child authenticates. Keep it.
+ */
+const CHILD_ENV_ALLOWLIST = /^CLAUDE_CODE_OAUTH_TOKEN$/;
+/**
+ * A copy of the current environment with nested-session leakage stripped, for
+ * the SDK's `options.env`. `ANTHROPIC_BASE_URL` and the `HTTP(S)_PROXY` vars are
+ * preserved (they are not matched by {@link NESTED_SESSION_ENV}) so API routing
+ * keeps working; `CLAUDE_CODE_OAUTH_TOKEN` is explicitly allowlisted so
+ * token-based auth survives on headless hosts.
+ */
+function buildChildEnv() {
+    const env = {};
+    const source = typeof process !== "undefined" ? process.env : {};
+    for (const [key, value] of Object.entries(source)) {
+        if (value === undefined)
+            continue;
+        if (NESTED_SESSION_ENV.test(key) && !CHILD_ENV_ALLOWLIST.test(key))
+            continue;
+        env[key] = value;
+    }
+    return env;
+}
+/**
+ * A DB skill name that is safe to use as a filesystem directory. The DB
+ * validates names (lowercase `a-z0-9-`), but path safety is enforced here too:
+ * a name with a separator or `.`-segment could otherwise escape the plugin
+ * dir. Defense in depth — an unsafe name is skipped, not written.
+ */
+function isFilesystemSafeSkillName(name) {
+    return /^[a-z0-9][a-z0-9-]{0,63}$/.test(name);
+}
+/**
+ * Write the user's DB skills to a throwaway local plugin the SDK's native skill
+ * loader can discover, and return `{ dir, names }` (or null when nothing was
+ * written). The layout is the Claude Code plugin format:
+ *
+ *   <dir>/.claude-plugin/plugin.json
+ *   <dir>/skills/<name>/SKILL.md   (name/description frontmatter + body)
+ *
+ * This is deliberately separate from `settingSources`: a `plugins` entry loads
+ * skills without enabling `~/.claude` / `.claude` settings or `CLAUDE.md`, and
+ * `skipMcpDiscovery` blocks any `.mcp.json` the dir might contain. The caller
+ * owns cleanup (see {@link ClaudeAgentProvider.generateLoop}'s `finally`).
+ */
+async function materializeSkillsPlugin(skills) {
+    const usable = skills.filter((s) => isFilesystemSafeSkillName(s.name) && s.content.trim().length > 0);
+    if (usable.length === 0)
+        return null;
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "nodetool-skills-"));
+    await fs.mkdir(path.join(dir, ".claude-plugin"), { recursive: true });
+    await fs.writeFile(path.join(dir, ".claude-plugin", "plugin.json"), JSON.stringify({
+        name: SKILLS_PLUGIN_NAME,
+        version: "1.0.0",
+        description: "User-defined skills from NodeTool."
+    }), "utf8");
+    const names = [];
+    for (const skill of usable) {
+        const skillDir = path.join(dir, "skills", skill.name);
+        await fs.mkdir(skillDir, { recursive: true });
+        // JSON-stringify the description: a JSON string is a valid YAML double-
+        // quoted scalar, so colons / quotes / newlines can't break the frontmatter.
+        const md = [
+            "---",
+            `name: ${skill.name}`,
+            `description: ${JSON.stringify(skill.description)}`,
+            "---",
+            "",
+            skill.content.trim(),
+            ""
+        ].join("\n");
+        await fs.writeFile(path.join(skillDir, "SKILL.md"), md, "utf8");
+        names.push(skill.name);
+    }
+    return { dir, names };
+}
+/** Pull a text/thinking delta out of a partial `stream_event`, if any. */
+function partialDelta(msg) {
+    const event = msg.event;
+    if (event.type !== "content_block_delta")
+        return null;
+    const delta = event.delta;
+    if (delta.type === "text_delta")
+        return { text: delta.text };
+    if (delta.type === "thinking_delta")
+        return { thinking: delta.thinking };
+    return null;
+}
+/** The concrete dated model id, captured from a partial `message_start`. */
+function capturedModelFromPartial(msg) {
+    const event = msg.event;
+    if (event.type !== "message_start")
+        return null;
+    const model = event.message?.model;
+    return isNonEmptyString(model) && model !== "<synthetic>" ? model : null;
+}
+/** Text/thinking blocks of a final assistant message, kept separate. */
+function finalBlocks(msg) {
+    const content = msg.message?.content;
+    if (!Array.isArray(content))
+        return [];
+    const out = [];
+    for (const block of content) {
+        if (block.type === "text" && isString(block.text)) {
+            out.push({ content: block.text, thinking: false });
+        }
+        else if (block.type === "thinking" && isString(block.thinking)) {
+            out.push({ content: block.thinking, thinking: true });
+        }
+    }
+    return out;
+}
+/**
+ * Recover the plain tool name from what the model emitted.
+ *
+ * Two prefixes get stripped, in order:
+ *  - `mcp__<server>__`, which the SDK adds to in-process MCP tool names.
+ *  - `tools.`, the retired guest toolbelt's call form, which models still
+ *    turn into a top-level tool name. Without this the call reaches no tool
+ *    at all.
+ */
+function stripToolPrefix(name) {
+    let n = isString(name) ? name : "";
+    if (n.startsWith(TOOL_PREFIX))
+        n = n.slice(TOOL_PREFIX.length);
+    if (n.startsWith(GUEST_TOOL_PREFIX))
+        n = n.slice(GUEST_TOOL_PREFIX.length);
+    return n;
+}
+/** Split a final assistant message into its text and its tool calls. */
+function assistantParts(msg) {
+    const content = msg.message?.content;
+    let text = "";
+    const toolCalls = [];
+    if (Array.isArray(content)) {
+        for (const raw of content) {
+            const b = raw;
+            if (b.type === "text" && isString(b.text)) {
+                text += b.text;
+            }
+            else if (b.type === "tool_use") {
+                toolCalls.push({
+                    id: isString(b.id) ? b.id : `call_${toolCalls.length}`,
+                    name: stripToolPrefix(b.name),
+                    args: isObjectLike(b.input)
+                        ? b.input
+                        : {}
+                });
+            }
+        }
+    }
+    return { text, toolCalls };
+}
+/** Extract `tool_result` blocks from a user message the SDK emitted. */
+function toolResultsFromUser(msg) {
+    const content = msg.message?.content;
+    const out = [];
+    if (Array.isArray(content)) {
+        for (const raw of content) {
+            const b = raw;
+            if (b.type === "tool_result" && isString(b.tool_use_id)) {
+                out.push({
+                    toolCallId: b.tool_use_id,
+                    content: toolResultText(b.content)
+                });
+            }
+        }
+    }
+    return out;
+}
+/** Flatten an MCP tool-result content payload to text. */
+function toolResultText(content) {
+    if (isString(content))
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .map((c) => {
+            const cc = c;
+            return cc.type === "text" && isString(cc.text) ? cc.text : "";
+        })
+            .join("");
+    }
+    return "";
+}
+/**
+ * Build an in-process MCP tool definition that bridges a NodeTool
+ * {@link ProviderTool} to the harness's tool executor. The JSON-Schema input is
+ * shimmed to the Zod raw shape the SDK expects.
+ */
+function toolDefinition(tool, run, resolveMedia) {
+    return {
+        name: tool.name,
+        description: tool.description ?? "",
+        inputSchema: jsonSchemaToZodShape(tool.inputSchema),
+        handler: async (toolArgs) => {
+            const result = await run(tool.name, toolArgs ?? {});
+            const resolved = Array.isArray(result) &&
+                result.some((part) => part.type === "image_url") &&
+                resolveMedia
+                ? await resolveMedia([{ role: "user", content: result }])
+                : null;
+            const content = resolved?.[0]?.content;
+            return {
+                content: toolResultToMcpContent(Array.isArray(content) ? content : result)
+            };
+        }
+    };
+}
+/**
+ * Decode a NodeTool image content part into an MCP image block (raw base64 +
+ * mimeType). Returns null for a remote URL we cannot inline — MCP image content
+ * is base64-only, so the caller reports that the image could not be shown.
+ */
+function toMcpImageBlock(image) {
+    let base64;
+    let mimeType = image.mimeType;
+    const fromDataUri = (uri) => {
+        const match = /^data:([^;,]+)?(;base64)?,([\s\S]*)$/.exec(uri);
+        if (!match)
+            return;
+        mimeType = mimeType ?? match[1] ?? "image/png";
+        base64 = match[2]
+            ? (match[3] ?? "")
+            : Buffer.from(decodeURIComponent(match[3] ?? "")).toString("base64");
+    };
+    if (isString(image.data)) {
+        if (image.data.startsWith("data:"))
+            fromDataUri(image.data);
+        else
+            base64 = image.data;
+    }
+    else if (image.data instanceof Uint8Array) {
+        base64 = Buffer.from(image.data).toString("base64");
+    }
+    if (!base64 && isString(image.uri) && image.uri.startsWith("data:")) {
+        fromDataUri(image.uri);
+    }
+    if (!base64)
+        return null;
+    return { type: "image", data: base64, mimeType: mimeType ?? "image/png" };
+}
+/**
+ * Convert a tool result into MCP content blocks. Text passes through; image
+ * parts become MCP image blocks (the SDK forwards them to Claude as real
+ * images). An image that can't be inlined becomes a failure note.
+ */
+export function toolResultToMcpContent(result) {
+    if (isString(result)) {
+        return [{ type: "text", text: result }];
+    }
+    const blocks = [];
+    for (const part of result) {
+        if (part.type === "text") {
+            blocks.push({ type: "text", text: part.text });
+        }
+        else if (part.type === "image_url") {
+            const img = toMcpImageBlock(part.image);
+            if (img)
+                blocks.push(img);
+            else {
+                blocks.push({
+                    type: "text",
+                    text: isString(part.image.uri)
+                        ? `[image could not be shown: ${part.image.uri}]`
+                        : "[image could not be shown]"
+                });
+            }
+        }
+    }
+    if (blocks.length === 0) {
+        blocks.push({ type: "text", text: "[no content]" });
+    }
+    return blocks;
+}
+/** Convert a JSON-Schema object's properties to a Zod raw shape. */
+function jsonSchemaToZodShape(schema) {
+    const props = schema?.properties ?? {};
+    const required = new Set(schema?.required ?? []);
+    const shape = {};
+    for (const [key, raw] of Object.entries(props)) {
+        let zt = jsonPropToZod(raw);
+        if (!required.has(key))
+            zt = zt.optional();
+        shape[key] = zt;
+    }
+    return shape;
+}
+/** Convert one JSON-Schema property to a Zod type (the subset NodeTool uses). */
+function jsonPropToZod(prop) {
+    const desc = isString(prop?.description) ? prop.description : undefined;
+    let zt;
+    switch (prop?.type) {
+        case "string":
+            zt = z.string();
+            break;
+        case "number":
+        case "integer":
+            zt = z.number();
+            break;
+        case "boolean":
+            zt = z.boolean();
+            break;
+        case "array":
+            zt = z.array(prop.items
+                ? jsonPropToZod(prop.items)
+                : z.unknown());
+            break;
+        case "object": {
+            const shape = jsonSchemaToZodShape(prop);
+            // Free-form objects (no declared sub-properties — e.g. add_node's
+            // `node_properties`) must keep arbitrary keys. `z.object({})` strips
+            // every key, silently dropping all node configuration on the SDK tool
+            // bridge; passthrough preserves the nested values.
+            zt =
+                Object.keys(shape).length > 0
+                    ? z.object(shape)
+                    : z.object({}).passthrough();
+            break;
         }
+        default:
+            zt = z.unknown();
     }
-    isContextLengthError(error) {
-        if (error instanceof ClaudeAgentError)
-            return error.kind === "context_length";
-        const msg = String(error).toLowerCase();
-        return (msg.includes("context length") ||
-            msg.includes("context window") ||
-            msg.includes("token limit") ||
-            msg.includes("too long") ||
-            msg.includes("maximum context"));
-    }
-    isAuthError(error) {
-        if (error instanceof ClaudeAgentError)
-            return error.kind === "auth";
-        return super.isAuthError(error);
-    }
-    isRateLimitError(error) {
-        if (error instanceof ClaudeAgentError)
-            return error.kind === "rate_limit";
-        return super.isRateLimitError(error);
+    return desc ? zt.describe(desc) : zt;
+}
+/** Build a descriptive Error from a non-success `result` message. */
+function resultError(msg) {
+    const parts = [`Claude Agent SDK query failed (${msg.subtype})`];
+    if ("errors" in msg && Array.isArray(msg.errors) && msg.errors.length) {
+        parts.push(msg.errors.join("; "));
+    }
+    else if ("result" in msg && isNonEmptyString(msg.result)) {
+        parts.push(msg.result);
+    }
+    const denials = (msg).permission_denials;
+    if (Array.isArray(denials) && denials.length) {
+        parts.push(`permission denied: ${denials.map((d) => d.tool_name ?? "?").join(", ")}`);
+    }
+    return new Error(parts.join(": "));
+}
+/** Flatten a message's content to plain text (text blocks only). */
+function textOf(content) {
+    if (content == null)
+        return "";
+    if (isString(content))
+        return content;
+    return content
+        .filter((c) => c.type === "text")
+        .map((c) => c.text)
+        .join("");
+}
+/** Join all system messages into the replacement system prompt. */
+function extractSystemPrompt(messages) {
+    const system = messages
+        .filter((m) => m.role === "system")
+        .map((m) => textOf(m.content))
+        .filter(Boolean)
+        .join("\n\n");
+    return system || DEFAULT_SYSTEM_PROMPT;
+}
+/**
+ * The new turn(s) to send when resuming: only the user messages added since the
+ * session's checkpoint. Assistant messages in the slice were produced by the
+ * resumed session itself, so they are already known to it and must not be
+ * replayed (re-feeding them would present the model its own prior answer as
+ * user input).
+ */
+function buildResumeDelta(messages, checkpoint) {
+    return messages
+        .slice(checkpoint)
+        .filter((m) => m.role === "user")
+        .map((m) => textOf(m.content))
+        .filter(Boolean)
+        .join("\n\n");
+}
+/**
+ * The prompt for a fresh session. A lone user turn is sent verbatim. When there
+ * is pre-existing FOREIGN history (a cold thread, a model switch, or an
+ * edited/branched conversation) we prime context ONCE with a single delimited
+ * user message instead of rebuilding a `Human:/Assistant:` transcript — the SDK
+ * cannot import external assistant turns, so this is deliberate context priming,
+ * not a faithful reconstruction. Only final assistant TEXT is included
+ * (thinking is stripped by {@link textOf}).
+ */
+function buildFreshPrompt(messages) {
+    const convo = messages.filter((m) => m.role !== "system");
+    if (convo.length === 0)
+        return "";
+    if (convo.length === 1 && convo[0].role === "user") {
+        return textOf(convo[0].content);
     }
+    const last = convo[convo.length - 1];
+    const newTurn = last.role === "user" ? textOf(last.content) : "";
+    const prior = last.role === "user" ? convo.slice(0, -1) : convo;
+    const transcript = prior
+        .map((m) => {
+        const text = textOf(m.content);
+        if (!text)
+            return "";
+        return `${m.role === "assistant" ? "Assistant" : "User"}: ${text}`;
+    })
+        .filter(Boolean)
+        .join("\n\n");
+    const primed = transcript
+        ? `<conversation_so_far>\n${transcript}\n</conversation_so_far>`
+        : "";
+    return [primed, newTurn].filter(Boolean).join("\n\n");
 }
 //# sourceMappingURL=claude-agent-provider.js.map