wave-agent-sdk 1.0.7 → 1.0.9

package/dist/tools/bashTool.js

@@ -6,6 +6,7 @@ import { logger } from "../utils/globalLogger.js";
 import { resolveShellPath } from "../utils/shellResolver.js";
 import { toPosixPath } from "../utils/path.js";
 import { stripAnsiColors } from "../utils/stringUtils.js";
+import { WindowsStreamDecoder } from "../utils/encoding.js";
 import { processToolResult } from "../utils/toolResultStorage.js";
 import { BASH_MAX_OUTPUT_CHARS } from "../constants/toolLimits.js";
 import { BASH_TOOL_NAME, GLOB_TOOL_NAME, GREP_TOOL_NAME, READ_TOOL_NAME, EDIT_TOOL_NAME, WRITE_TOOL_NAME, } from "../constants/tools.js";
@@ -219,17 +220,14 @@ The working directory persists between commands. Try to maintain your current wo
             const { id: taskId } = backgroundTaskManager.startShell(command, undefined, context.workdir);
             const task = backgroundTaskManager.getTask(taskId);
             const outputPath = task?.outputPath;
-            const backgroundMsg = [
-                `Command started in background with ID: ${taskId}.`,
-                `You will be notified automatically when it completes.`,
-                outputPath
-                    ? `output_file: ${outputPath}`
-                    : `Use ${READ_TOOL_NAME} tool with task_id="${taskId}" to read the output.`,
-            ].join("\n");
+            const backgroundMsg = outputPath
+                ? `Command running in background with ID: ${taskId}. Output is being written to: ${outputPath}`
+                : `Command running in background with ID: ${taskId}. Use ${READ_TOOL_NAME} tool with task_id="${taskId}" to read the output.`;
             return {
                 success: true,
                 content: recoveryNotice + backgroundMsg,
                 shortResult: `Background process ${taskId} started${outputPath ? ` → ${outputPath}` : ""}`,
+                backgroundTaskId: taskId,
             };
         }
         // Foreground execution (original behavior)
@@ -253,6 +251,10 @@ The working directory persists between commands. Try to maintain your current wo
             let isAborted = false;
             let isBackgrounded = false;
             let isFinished = false;
+            // On Windows, native tools (taskkill, powershell, ...) write GBK (cp936)
+            // instead of UTF-8; decode their byte streams accordingly (issue #1753).
+            const stdoutDecoder = process.platform === "win32" ? new WindowsStreamDecoder() : null;
+            const stderrDecoder = process.platform === "win32" ? new WindowsStreamDecoder() : null;
             // Best-effort cleanup of the temp CWD file — used by abort/error/exit paths
             const cleanupTempFile = () => {
                 try {
@@ -303,9 +305,10 @@ The working directory persists between commands. Try to maintain your current wo
                             const outputPath = task?.outputPath;
                             resolve({
                                 success: true,
-                                content: `Command moved to background with ID: ${taskId}.${outputPath ? ` Real-time output: ${outputPath}` : ""}`,
+                                content: `Command was manually backgrounded by user with ID: ${taskId}.${outputPath ? ` Output is being written to: ${outputPath}` : ""}`,
                                 shortResult: `Process ${taskId} backgrounded`,
-                                isManuallyBackgrounded: true,
+                                backgroundedByUser: true,
+                                backgroundTaskId: taskId,
                             });
                         }
                         else {
@@ -337,8 +340,10 @@ The working directory persists between commands. Try to maintain your current wo
                             logger.info(`[Bash] Command timed out after ${timeout}ms, auto-backgrounded as ${taskId}`);
                             resolve({
                                 success: true,
-                                content: `Command timed out after ${timeout / 1000} seconds and was moved to background with ID: ${taskId}.${outputPath ? ` Real-time output: ${outputPath}` : ""}`,
-                                shortResult: `Process ${taskId} auto-backgrounded (timeout)`,
+                                content: `Command exceeded the timeout (${timeout / 1000}s) and was moved to the background with ID: ${taskId}. It is still running — you will be notified when it completes.${outputPath ? ` Output is being written to: ${outputPath}` : ""}`,
+                                shortResult: `Process ${taskId} auto-backgrounded`,
+                                assistantAutoBackgrounded: true,
+                                backgroundTaskId: taskId,
                             });
                         }
                         else {
@@ -416,14 +421,14 @@ The working directory persists between commands. Try to maintain your current wo
             }
             child.stdout?.on("data", (data) => {
                 if (!isAborted && !isBackgrounded && !runInBackground) {
-                    const chunk = stripAnsiColors(data.toString());
+                    const chunk = stripAnsiColors(stdoutDecoder ? stdoutDecoder.push(data) : data.toString());
                     outputBuffer += chunk;
                     updateRealtimeResults();
                 }
             });
             child.stderr?.on("data", (data) => {
                 if (!isAborted && !isBackgrounded && !runInBackground) {
-                    const chunk = stripAnsiColors(data.toString());
+                    const chunk = stripAnsiColors(stderrDecoder ? stderrDecoder.push(data) : data.toString());
                     errorBuffer += chunk;
                     updateRealtimeResults();
                 }
@@ -467,6 +472,12 @@ The working directory persists between commands. Try to maintain your current wo
                         }
                     }
                     const exitCode = code ?? 0;
+                    // Decode any bytes still held at stream end (e.g. a trailing UTF-8
+                    // character split across the last chunk).
+                    if (stdoutDecoder)
+                        outputBuffer += stdoutDecoder.flush();
+                    if (stderrDecoder)
+                        errorBuffer += stderrDecoder.flush();
                     const combinedOutput = outputBuffer + (errorBuffer ? "\n" + errorBuffer : "");
                     // Prepend CWD change message to output if present
                     const finalOutput = recoveryNotice +

package/dist/tools/editTool.js

@@ -168,7 +168,11 @@ Usage:
             if (replaceAll) {
                 // Replace all matches
                 const regex = new RegExp(escapeRegExp(matchedOldString), "g");
-                newContent = normalizedContent.replace(regex, newString);
+                // Function replacer (claude-code's applyEditToFile approach): newString
+                // is inserted literally, never parsed as a $ replacement template. A
+                // string replacer would expand $& to the matched text, $$ to a single
+                // $, and `$` could even truncate and duplicate the file (issue #1752).
+                newContent = normalizedContent.replace(regex, () => newString);
                 replacementCount = (normalizedContent.match(regex) || []).length;
             }
             else {
@@ -181,7 +185,8 @@ Usage:
                         error: `old_string appears ${matches} times in the file. Either provide a larger string with more surrounding context to make it unique or use replace_all=true to change every instance.`,
                     };
                 }
-                newContent = normalizedContent.replace(matchedOldString, newString);
+                // Function replacer: see note above — $ in newString stays literal
+                newContent = normalizedContent.replace(matchedOldString, () => newString);
                 replacementCount = 1;
             }
             // Permission check after validation but before real operation

package/dist/tools/types.d.ts

@@ -37,7 +37,9 @@ export interface ToolResult {
         data: string;
         mediaType?: string;
     }>;
-    isManuallyBackgrounded?: boolean;
+    backgroundTaskId?: string;
+    backgroundedByUser?: boolean;
+    assistantAutoBackgrounded?: boolean;
     metadata?: Record<string, unknown>;
 }
 export interface ToolContext {

package/dist/tools/webFetchTool.js

@@ -2,12 +2,18 @@ import TurndownService from "turndown";
 import { LRUCache } from "lru-cache";
 import { WEB_FETCH_TOOL_NAME } from "../constants/tools.js";
 import { logger } from "../utils/globalLogger.js";
+import { isArtifactEnabled } from "../services/artifactAvailability.js";
+import { authService, createAuthAwareFetch } from "../services/authService.js";
+import { recordVersion } from "../services/artifactSession.js";
+import { buildPersistedOutputMessage, generatePreview, persistToolResult, } from "../utils/toolResultStorage.js";
 // --- Security Limits ---
 const MAX_HTTP_CONTENT_LENGTH = 10 * 1024 * 1024; // 10MB
 const FETCH_TIMEOUT_MS = 60000; // 60s
 const MAX_REDIRECTS = 10;
 const MAX_MARKDOWN_LENGTH = 100000;
 const USER_AGENT = "Wave-User (+https://github.com/netease-lcap/wave-agent)";
+/** Artifact HTML beyond this size is persisted to a temp file (path + head preview). */
+const ARTIFACT_PREVIEW_BYTES = 2 * 1024; // ~2KB
 // --- Cache (LRU with 15min TTL, 50MB max) ---
 const CACHE_TTL = 15 * 60 * 1000; // 15 minutes
 const CACHE_MAX_BYTES = 50 * 1024 * 1024; // 50MB
@@ -73,6 +79,124 @@ function isPermittedRedirect(originalUrl, redirectUrl) {
         return false;
     }
 }
+// --- Artifact read channel ---
+/** Extract the artifact slug from a `{host}/code/artifact/{slug}` URL. */
+function extractArtifactSlug(url) {
+    try {
+        const parsed = new URL(url);
+        const match = parsed.pathname.match(/^\/code\/artifact\/([^/]+)\/?$/);
+        return match ? decodeURIComponent(match[1]) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Fetch artifact metadata (`via=model_read`) then the HTML content (Bearer).
+ * Returns markdown (HTML converted via turndown) on success.
+ */
+async function readArtifact(url, slug, abortSignal) {
+    const serverUrl = authService.getServerUrl();
+    const authFetch = createAuthAwareFetch(globalThis.fetch);
+    const signal = abortSignal
+        ? AbortSignal.any([abortSignal, AbortSignal.timeout(FETCH_TIMEOUT_MS)])
+        : AbortSignal.timeout(FETCH_TIMEOUT_MS);
+    let meta;
+    try {
+        const metaRes = await authFetch(`${serverUrl}/api/frame/${encodeURIComponent(slug)}?via=model_read`, { method: "GET", signal });
+        if (metaRes.status === 404) {
+            return {
+                kind: "error",
+                error: `Artifact not found: ${url} (it may have been deleted)`,
+            };
+        }
+        if (!metaRes.ok) {
+            return {
+                kind: "error",
+                error: `Failed to fetch artifact metadata: ${metaRes.status} ${metaRes.statusText}`,
+            };
+        }
+        meta = (await metaRes.json());
+    }
+    catch (error) {
+        logger?.warn("Artifact read metadata failed", {
+            slug,
+            error: String(error),
+        });
+        return {
+            kind: "error",
+            error: `Failed to fetch artifact metadata: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    const contentUrl = typeof meta.contentUrl === "string" ? meta.contentUrl : "";
+    const version = typeof meta.version === "string" ? meta.version : "";
+    if (!contentUrl) {
+        return {
+            kind: "error",
+            error: "Artifact metadata did not include a contentUrl",
+        };
+    }
+    let html;
+    try {
+        const contentRes = await authFetch(new URL(contentUrl, serverUrl).toString(), { method: "GET", signal });
+        if (!contentRes.ok) {
+            return {
+                kind: "error",
+                error: `Failed to fetch artifact content: ${contentRes.status} ${contentRes.statusText}`,
+            };
+        }
+        html = await contentRes.text();
+    }
+    catch (error) {
+        logger?.warn("Artifact read content failed", {
+            slug,
+            error: String(error),
+        });
+        return {
+            kind: "error",
+            error: `Failed to fetch artifact content: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    const turndownService = new TurndownService();
+    const markdown = turndownService.turndown(html);
+    return {
+        kind: "ok",
+        slug,
+        version,
+        markdown,
+        bytes: new TextEncoder().encode(markdown).length,
+    };
+}
+/**
+ * Process an artifact read result: persist content >~2KB to a temp file
+ * (return file path + head preview), run the prompt, attach artifactRead metadata.
+ */
+async function processArtifactRead(url, prompt, markdown, slug, version, context) {
+    const bytes = new TextEncoder().encode(markdown).length;
+    let aiInput = markdown;
+    let persistedMessage = "";
+    if (bytes > ARTIFACT_PREVIEW_BYTES) {
+        const filePath = persistToolResult(markdown, "artifact");
+        if (filePath) {
+            persistedMessage = buildPersistedOutputMessage(markdown.length, filePath, generatePreview(markdown));
+            aiInput = persistedMessage;
+        }
+        else {
+            aiInput =
+                markdown.substring(0, MAX_MARKDOWN_LENGTH) +
+                    "\n\n... (content truncated, failed to persist full output)";
+        }
+    }
+    const result = await processWithAI(url, prompt, aiInput, 200, "OK", context, bytes);
+    result.metadata = { artifactRead: { slug, ver: version } };
+    if (persistedMessage) {
+        // Append the persisted-output message so the model can Read the full content.
+        result.content = result.content
+            ? result.content + "\n\n" + persistedMessage
+            : persistedMessage;
+    }
+    return result;
+}
 // --- Tool ---
 export const webFetchTool = {
     name: WEB_FETCH_TOOL_NAME,
@@ -141,6 +265,23 @@ Usage notes:
                 error: validation.error,
             };
         }
+        // Artifact URL interception: {host}/code/artifact/{slug} goes through the
+        // dedicated read channel (via=model_read + Bearer) instead of a public fetch.
+        // Only when the Artifact tool is enabled (spec 6.4: disabled = no interception).
+        if (isArtifactEnabled(context.workdir)) {
+            const artifactSlug = extractArtifactSlug(url);
+            if (artifactSlug) {
+                const readResult = await readArtifact(url, artifactSlug, context.abortSignal);
+                if (readResult.kind === "error") {
+                    return { success: false, content: "", error: readResult.error };
+                }
+                if (context.sessionId && readResult.version) {
+                    // Keep the stale-version guard in sync with what the model has seen.
+                    recordVersion(context.sessionId, artifactSlug, readResult.version);
+                }
+                return processArtifactRead(url, prompt, readResult.markdown, artifactSlug, readResult.version, context);
+            }
+        }
         try {
             const cached = cache.get(url);
             if (cached) {

package/dist/types/agent.d.ts

@@ -25,6 +25,8 @@ export interface AgentOptions {
     fetch?: ClientOptions["fetch"];
     model?: string;
     fastModel?: string;
+    /** Vision-capable model used by the builtin vision subagent (resolved from WAVE_VISION_MODEL env var). */
+    visionModel?: string;
     maxInputTokens?: number;
     maxTokens?: number;
     /** Preferred language for agent communication */

package/dist/types/config.d.ts

@@ -22,6 +22,8 @@ export interface ModelCapabilities {
 export interface ModelConfig {
     model?: string;
     fastModel?: string;
+    /** Vision-capable model for image recognition subagents (resolved from WAVE_VISION_MODEL env var). */
+    visionModel?: string;
     maxTokens?: number;
     permissionMode?: PermissionMode;
     capabilities?: ModelCapabilities;

package/dist/types/configuration.d.ts

@@ -55,6 +55,8 @@ export interface WaveConfiguration {
         /** Base ref for new worktrees: "fresh" (origin/<default-branch>, default) | "head" (local HEAD) */
         baseRef?: "fresh" | "head";
     };
+    /** Whether the Artifact tool is enabled. Unset follows the code default constant (ARTIFACT_DEFAULT_ENABLED). */
+    enableArtifact?: boolean;
 }
 /**
  * Legacy alias for backward compatibility - will be deprecated

package/dist/types/messaging.d.ts

@@ -52,7 +52,9 @@ export interface ToolBlock {
     error?: string | Error;
     compactParams?: string;
     parametersChunk?: string;
-    isManuallyBackgrounded?: boolean;
+    backgroundTaskId?: string;
+    backgroundedByUser?: boolean;
+    assistantAutoBackgrounded?: boolean;
     timestamp?: number;
 }
 export interface ImageBlock {

package/dist/types/permissions.d.ts

@@ -36,9 +36,11 @@ export interface ToolPermissionContext {
     toolCallId?: string;
     /** The content of the plan being exited from */
     planContent?: string;
+    /** Optional warning line to surface in the confirmation UI (e.g. shared-live redeploy impact) */
+    warning?: string;
 }
 /** List of tools that require permission checks in default mode */
-export declare const RESTRICTED_TOOLS: readonly ["Edit", "Bash", "Write", "EnterPlanMode", "ExitPlanMode", "AskUserQuestion"];
+export declare const RESTRICTED_TOOLS: readonly ["Edit", "Bash", "Write", "EnterPlanMode", "ExitPlanMode", "AskUserQuestion", "Artifact"];
 /** Type for restricted tool names */
 export type RestrictedTool = (typeof RESTRICTED_TOOLS)[number];
 export declare const OPERATION_CANCELLED_BY_USER = "Operation cancelled by user";

package/dist/types/permissions.js

@@ -2,7 +2,7 @@
  * Permission system types for Wave Agent SDK
  * Dependencies: None
  */
-import { EDIT_TOOL_NAME, BASH_TOOL_NAME, WRITE_TOOL_NAME, ENTER_PLAN_MODE_TOOL_NAME, EXIT_PLAN_MODE_TOOL_NAME, ASK_USER_QUESTION_TOOL_NAME, } from "../constants/tools.js";
+import { EDIT_TOOL_NAME, BASH_TOOL_NAME, WRITE_TOOL_NAME, ENTER_PLAN_MODE_TOOL_NAME, EXIT_PLAN_MODE_TOOL_NAME, ASK_USER_QUESTION_TOOL_NAME, ARTIFACT_TOOL_NAME, } from "../constants/tools.js";
 /** List of tools that require permission checks in default mode */
 export const RESTRICTED_TOOLS = [
     EDIT_TOOL_NAME,
@@ -11,5 +11,6 @@ export const RESTRICTED_TOOLS = [
     ENTER_PLAN_MODE_TOOL_NAME,
     EXIT_PLAN_MODE_TOOL_NAME,
     ASK_USER_QUESTION_TOOL_NAME,
+    ARTIFACT_TOOL_NAME,
 ];
 export const OPERATION_CANCELLED_BY_USER = "Operation cancelled by user";

package/dist/utils/bashParser.d.ts

@@ -46,6 +46,12 @@ export interface ToolRule {
     depth: number;
     scopeFlags?: string[];
 }
+/**
+ * Global scope flags for git that only change the target repository or
+ * configuration, not the subcommand being run. Shared by TOOL_RULES (smart
+ * prefix extraction) and stripGitScopePrefix (rule matching).
+ */
+export declare const GIT_SCOPE_FLAGS: string[];
 export declare const TOOL_RULES: Record<string, ToolRule>;
 /**
  * Registry of dangerous subcommands for specific tools.
@@ -71,6 +77,14 @@ export declare function hasProcessSubstitution(command: string): boolean;
  * sed -i modifies files in place and must NOT be auto-allowed. FR-019.5.
  */
 export declare function hasSedInPlace(command: string): boolean;
+/**
+ * Removes leading git global scope flags (e.g. `git -C <path>`, `git -c <key>=<value>`,
+ * `git --git-dir <path>`) from a command string, so that `git -C /tmp/foo status` is
+ * classified the same as `git status`. Only the leading sequence before the git
+ * subcommand is stripped; the remainder is re-joined with single spaces.
+ * Returns the input unchanged when nothing is stripped.
+ */
+export declare function stripGitScopePrefix(command: string): string;
 /**
  * Extracts a "smart prefix" from a bash command based on common developer tools.
  * Returns null if the command is blacklisted or cannot be safely prefix-matched.

package/dist/utils/bashParser.js

@@ -500,6 +500,18 @@ export const READ_ONLY_COMMANDS = [
     "bc",
     "sleep",
 ];
+/**
+ * Global scope flags for git that only change the target repository or
+ * configuration, not the subcommand being run. Shared by TOOL_RULES (smart
+ * prefix extraction) and stripGitScopePrefix (rule matching).
+ */
+export const GIT_SCOPE_FLAGS = [
+    "-C",
+    "-c",
+    "--directory",
+    "--work-tree",
+    "--git-dir",
+];
 export const TOOL_RULES = {
     // Node/JS
     npm: { depth: 2, scopeFlags: ["--prefix", "-C", "--registry"] },
@@ -517,7 +529,7 @@ export const TOOL_RULES = {
     // Git
     git: {
         depth: 2,
-        scopeFlags: ["-C", "-c", "--directory", "--work-tree", "--git-dir"],
+        scopeFlags: GIT_SCOPE_FLAGS,
     },
     // Python
     python: { depth: 2 },
@@ -670,6 +682,38 @@ export function hasSedInPlace(command) {
         return false;
     return tokens.some((token) => /^-i(\..*)?$/.test(token));
 }
+/**
+ * Removes leading git global scope flags (e.g. `git -C <path>`, `git -c <key>=<value>`,
+ * `git --git-dir <path>`) from a command string, so that `git -C /tmp/foo status` is
+ * classified the same as `git status`. Only the leading sequence before the git
+ * subcommand is stripped; the remainder is re-joined with single spaces.
+ * Returns the input unchanged when nothing is stripped.
+ */
+export function stripGitScopePrefix(command) {
+    const trimmed = command.trim();
+    if (!/^git(?:\s|$)/.test(trimmed))
+        return command;
+    const tokens = trimmed.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) || [];
+    if (tokens.length === 0 || tokens[0] !== "git")
+        return command;
+    let i = 1;
+    while (i < tokens.length) {
+        const token = tokens[i];
+        const eqIndex = token.indexOf("=");
+        const flag = eqIndex > 0 ? token.slice(0, eqIndex) : token;
+        if (!GIT_SCOPE_FLAGS.includes(flag))
+            break;
+        if (eqIndex > 0) {
+            i++; // --flag=value form carries its own value
+        }
+        else {
+            i += 2; // skip the flag and its argument
+        }
+    }
+    if (i === 1)
+        return command;
+    return ["git", ...tokens.slice(i)].join(" ");
+}
 /**
  * Extracts a "smart prefix" from a bash command based on common developer tools.
  * Returns null if the command is blacklisted or cannot be safely prefix-matched.

package/dist/utils/containerSetup.js

@@ -219,6 +219,14 @@ export function setupAgentContainer(setupOptions) {
         onReload: () => {
             const models = configurationService.getConfiguredModels();
             callbacks.onConfiguredModelsChange?.(models);
+            // Re-evaluate feature-gated tools (e.g. Artifact behind
+            // enableArtifact) so toggling the flag applies without a restart.
+            toolManager.reloadFeatureGatedTools();
+            // Same gate for the builtin /artifact skill: refresh emits "refreshed"
+            // so slash-command registration follows enableArtifact.
+            void skillManager.reloadFeatureGatedSkills().catch((error) => {
+                logger.error("Failed to reload feature-gated skills:", error);
+            });
         },
     });
     container.register("LiveConfigManager", liveConfigManager);

package/dist/utils/convertMessagesForAPI.js

@@ -158,14 +158,38 @@ export function convertMessagesForAPI(messages, options) {
                     tool_calls = undefined;
                 }
             }
-            // Construct assistant message - only add if there is meaningful content or tool calls
+            // Construct assistant message - only add if there is meaningful content,
+            // tool calls, or reasoning content. Reasoning-only messages (a truncated
+            // turn that produced nothing but thinking) must be preserved so the next
+            // round can continue from the previous reasoning instead of starting
+            // over (aligned with Claude Code's thinking trajectory preservation).
             const hasContent = content && content.trim().length > 0;
             const hasToolCalls = tool_calls && tool_calls.length > 0;
-            if (hasContent || hasToolCalls) {
+            const hasReasoning = reasoning_content && reasoning_content.trim().length > 0;
+            if (hasContent || hasToolCalls || hasReasoning) {
+                // OpenAI-compatible upstreams reject assistant messages where neither
+                // content nor tool_calls is set — a reasoning_content-only message
+                // gets stripped and returns 400 "content or tool_calls must be set"
+                // (this is fine for Claude Code, whose thinking blocks ARE content).
+                // When a turn produced only thinking (interrupted/truncated
+                // mid-reasoning), the thinking stays on its native reasoning_content
+                // field (the channel reasoning models natively continue from), and
+                // content carries an explanatory note so the request stays valid and
+                // the model knows the thinking was cut off and auto-preserved.
+                // Tool calls are meaningful content of their own — a reasoning +
+                // tool-call turn is not truncated, so no note is injected.
+                const fallbackContent = hasContent
+                    ? content
+                    : hasReasoning && !hasToolCalls
+                        ? "[Note: The reasoning above was cut off before completion. It was auto-preserved from an interrupted or truncated turn — continue from where it left off, or disregard it if no longer relevant.]"
+                        : undefined;
                 const assistantMessage = {
                     role: "assistant",
-                    content: hasContent ? content : undefined,
+                    content: fallbackContent,
                     tool_calls,
+                    // Sent whenever reasoning exists: alongside real text it is the
+                    // turn's own thinking; in the fallback case it carries the
+                    // preserved thinking itself (content only holds the note).
                     ...(reasoning_content ? { reasoning_content } : {}),
                     ...(message.additionalFields ? { ...message.additionalFields } : {}),
                 };
@@ -196,12 +220,25 @@ export function convertMessagesForAPI(messages, options) {
                             type: "text",
                             text: "[User shared an image, but the current model does not support image recognition]",
                         });
+                        // Append source path metadata for local-file images so the main
+                        // model can delegate recognition to a vision subagent (which
+                        // reads the path with the Read tool). Inline dataURLs are
+                        // skipped — only persisted paths are delegatable.
+                        block.imageUrls.forEach((imageUrl) => {
+                            if (!imageUrl.startsWith("data:image/")) {
+                                contentParts.push({
+                                    type: "text",
+                                    text: `[Image source: ${imageUrl}]`,
+                                });
+                            }
+                        });
                     }
                     else {
                         block.imageUrls.forEach((imageUrl) => {
                             // Check if it's already base64, convert if not
+                            const isDataUrl = imageUrl.startsWith("data:image/");
                             let finalImageUrl = imageUrl;
-                            if (!imageUrl.startsWith("data:image/")) {
+                            if (!isDataUrl) {
                                 // If it's a file path, it needs to be converted to base64
                                 try {
                                     finalImageUrl = convertImageToBase64(imageUrl);
@@ -219,6 +256,16 @@ export function convertMessagesForAPI(messages, options) {
                                     detail: "auto",
                                 },
                             });
+                            // Aligned with Claude Code: when the image comes from a local
+                            // file (not an inline dataURL), append its source path as text
+                            // metadata so the model can reference the file with tools
+                            // (e.g. a vision-model subagent reading the image).
+                            if (!isDataUrl) {
+                                contentParts.push({
+                                    type: "text",
+                                    text: `[Image source: ${imageUrl}]`,
+                                });
+                            }
                         });
                     }
                 }

package/dist/utils/encoding.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Streaming byte-to-text decoder for bash tool output on Windows.
+ *
+ * Git Bash (MSYS) tools emit UTF-8, but native Windows programs (taskkill,
+ * powershell, ping, ...) write the system OEM code page — GBK (cp936) on
+ * zh-CN systems. Node's default `data.toString()` decodes every stream as
+ * UTF-8, so GBK bytes turn into U+FFFD mojibake (issue #1753).
+ *
+ * Strategy (per-chunk buffering, decide-once):
+ * - Accumulate raw bytes; try strict UTF-8 (`fatal: true`) over everything
+ *   buffered so far. If it decodes cleanly, emit the text.
+ * - If strict UTF-8 fails, hold back up to 3 trailing bytes (a UTF-8
+ *   character split across chunk boundaries) and retry on the next chunk.
+ * - Once even the head is not valid UTF-8, the stream is GBK: re-decode all
+ *   buffered bytes with GBK and switch to GBK for every subsequent chunk.
+ * - `flush()` decodes any leftover buffered bytes (leniently) at stream end.
+ */
+export declare class WindowsStreamDecoder {
+    private pending;
+    private gbkDecoder;
+    /** Longest possible incomplete UTF-8 tail at a chunk boundary is 3 bytes. */
+    private static readonly MAX_UTF8_TRAIL_BYTES;
+    push(data: Buffer): string;
+    /** Decode any bytes still held at stream end (lenient UTF-8, else GBK). */
+    flush(): string;
+}
+/** Decode a single complete byte sequence (used for non-streaming reads). */
+export declare function decodeBytes(buf: Buffer): string;