@cjhyy/code-shell-core 0.6.0-rc.16 → 0.6.0-rc.18

package/dist/tool-system/builtin/drive-claude-code.js

@@ -4,6 +4,8 @@ import { backgroundJobRegistry } from "./background-jobs.js";
 import { readExternalChangedFiles } from "../../cc-orchestrator/external-agent-changes.js";
 import { isExistingDirectory, normalizeCwdPath } from "../../cc-orchestrator/cwd-normalize.js";
 import { notificationQueue } from "./agent-notifications.js";
+import { existsSync, realpathSync, statSync } from "node:fs";
+import { extname, isAbsolute, relative, resolve, sep } from "node:path";
 import { externalAgentSessionStore, } from "../../cc-orchestrator/external-agent-session-store.js";
 import { logger } from "../../logging/logger.js";
 export const DRIVE_AGENT_FOREGROUND_HANDOFF_MS = 110_000;
@@ -40,19 +42,48 @@ export const driveAgentToolDef = {
     inputSchema: {
         type: "object",
         properties: {
-            prompt: { type: "string", description: "The task for the agent. Make it COMPLETE and self-contained: state the goal, a concrete definition of done, and (for open-ended work) an explicit scope bound so it finishes end-to-end and verifies its own work rather than sprawling or stopping half-way." },
-            cli: { type: "string", enum: ["claude", "codex"], description: "Which external CLI to drive. 'claude' = Claude Code (default), 'codex' = OpenAI Codex. resumeSessionId is only valid against the same cli that produced it." },
-            resumeSessionId: { type: "string", description: "Existing session id to resume (keeps context). Must come from a prior run of the SAME cli. Omit for a fresh session." },
+            prompt: {
+                type: "string",
+                description: "The task for the agent. Make it COMPLETE and self-contained: state the goal, a concrete definition of done, and (for open-ended work) an explicit scope bound so it finishes end-to-end and verifies its own work rather than sprawling or stopping half-way.",
+            },
+            cli: {
+                type: "string",
+                enum: ["claude", "codex"],
+                description: "Which external CLI to drive. 'claude' = Claude Code (default), 'codex' = OpenAI Codex. resumeSessionId is only valid against the same cli that produced it.",
+            },
+            resumeSessionId: {
+                type: "string",
+                description: "Existing session id to resume (keeps context). Must come from a prior run of the SAME cli. Omit for a fresh session.",
+            },
             cwd: { type: "string", description: "Working directory the run operates in." },
-            permissionMode: { type: "string", enum: ["default", "acceptEdits", "bypassPermissions"], description: "Permission/sandbox level. Defaults to 'bypassPermissions' (full auto — needed so the agent's tools run unattended; there is no interactive approval loop here). For codex: default→read-only sandbox, acceptEdits→workspace-write, bypassPermissions→no sandbox. Pass 'default'/'acceptEdits' to gate." },
-            background: { type: "boolean", description: "Defaults to TRUE: run in the background and notify you on completion (right for long tasks). Pass false to run in the foreground and get the result inline (only for quick tasks)." },
+            attachmentPaths: {
+                type: "array",
+                items: { type: "string" },
+                description: "Optional local file paths to hand to the driven agent. Paths must resolve inside cwd. Images are also passed to Codex with -i when the installed Codex CLI supports it; otherwise all paths are listed in the prompt.",
+            },
+            permissionMode: {
+                type: "string",
+                enum: ["default", "acceptEdits", "bypassPermissions"],
+                description: "Permission/sandbox level. Defaults to 'bypassPermissions' (full auto — needed so the agent's tools run unattended; there is no interactive approval loop here). For codex: default→read-only sandbox, acceptEdits→workspace-write, bypassPermissions→no sandbox. Pass 'default'/'acceptEdits' to gate.",
+            },
+            background: {
+                type: "boolean",
+                description: "Defaults to TRUE: run in the background and notify you on completion (right for long tasks). Pass false to run in the foreground and get the result inline (only for quick tasks).",
+            },
         },
         required: ["prompt", "cwd"],
     },
 };
 const defaultRunner = (opts) => {
     const { adapter, command } = CLI_ADAPTERS[opts.cli];
-    return runAgentOnce(adapter, { command, prompt: opts.prompt, resumeSessionId: opts.resumeSessionId, cwd: opts.cwd, permissionMode: opts.permissionMode ?? "default" }, opts.signal);
+    return runAgentOnce(adapter, {
+        command,
+        prompt: opts.prompt,
+        resumeSessionId: opts.resumeSessionId,
+        cwd: opts.cwd,
+        permissionMode: opts.permissionMode ?? "default",
+        imagePaths: opts.imagePaths,
+    }, opts.signal);
 };
 function newDriveJobId() {
     return `cc-${process.hrtime.bigint().toString(36)}`;
@@ -72,6 +103,43 @@ function argSignal(args) {
 function startRun(runner, opts) {
     return Promise.resolve().then(() => runner(opts));
 }
+function resolveAttachmentPaths(raw, cwd) {
+    if (raw === undefined)
+        return { paths: [] };
+    if (!Array.isArray(raw))
+        return { paths: [], error: "attachmentPaths must be an array of strings" };
+    const cwdReal = realpathSync(cwd);
+    const paths = [];
+    for (const item of raw) {
+        if (typeof item !== "string" || !item.trim()) {
+            return { paths: [], error: "attachmentPaths must contain only non-empty strings" };
+        }
+        const candidate = isAbsolute(item) ? item : resolve(cwd, item);
+        if (!existsSync(candidate))
+            return { paths: [], error: `attachment path not found: ${item}` };
+        const real = realpathSync(candidate);
+        const rel = relative(cwdReal, real);
+        if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`)) {
+            return { paths: [], error: `attachment path is outside cwd: ${item}` };
+        }
+        const info = statSync(real);
+        if (!info.isFile())
+            return { paths: [], error: `attachment path is not a file: ${item}` };
+        paths.push(real);
+    }
+    return { paths };
+}
+const DRIVE_IMAGE_EXTS = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp"]);
+function appendAttachmentPrompt(prompt, paths) {
+    if (paths.length === 0)
+        return prompt;
+    const lines = ["", "Attached files:"];
+    for (const path of paths) {
+        const kind = DRIVE_IMAGE_EXTS.has(extname(path).toLowerCase()) ? "image" : "file";
+        lines.push(`- ${path} (${kind})`);
+    }
+    return `${prompt}\n${lines.join("\n")}`;
+}
 function recordSuccessfulSession(store, cli, cwd, result) {
     if (result.isError || !result.sessionId)
         return;
@@ -106,14 +174,28 @@ function attachDriveCompletion(params) {
         // (not just "a job finished"). Mirrors the video/sub-agent completion
         // path — enqueue lands in the same notificationQueue the wakeup drains.
         notificationQueue.enqueue(r.isError
-            ? { agentId: jobId, description: label, status: "failed", workKind: "cc", error: r.finalText || "(no output)", ccSessionId: r.sessionId || undefined, enqueuedAt: Date.now() }
-            : { agentId: jobId, description: label, status: "completed", workKind: "cc", finalText: r.finalText, ccSessionId: r.sessionId || undefined, enqueuedAt: Date.now() }, sessionId);
+            ? {
+                agentId: jobId,
+                description: label,
+                status: "failed",
+                workKind: "cc",
+                error: r.finalText || "(no output)",
+                ccSessionId: r.sessionId || undefined,
+                enqueuedAt: Date.now(),
+            }
+            : {
+                agentId: jobId,
+                description: label,
+                status: "completed",
+                workKind: "cc",
+                finalText: r.finalText,
+                ccSessionId: r.sessionId || undefined,
+                enqueuedAt: Date.now(),
+            }, sessionId);
         // Attribute the files the external agent changed by parsing its own
         // transcript (#6) — those Edit/Write calls are invisible to the host's
         // in-session aggregator. Best-effort; [] on any failure.
-        const changedFiles = r.sessionId
-            ? readExternalChangedFiles(cli, cwd, r.sessionId)
-            : [];
+        const changedFiles = r.sessionId ? readExternalChangedFiles(cli, cwd, r.sessionId) : [];
         // Retain the job in the panel with its result + the external CLI
         // session id + changed files.
         backgroundJobRegistry.finish(jobId, {
@@ -125,7 +207,14 @@ function attachDriveCompletion(params) {
     })
         .catch((err) => {
         const msg = err?.message ?? String(err);
-        notificationQueue.enqueue({ agentId: jobId, description: label, status: "failed", workKind: "cc", error: msg, enqueuedAt: Date.now() }, sessionId);
+        notificationQueue.enqueue({
+            agentId: jobId,
+            description: label,
+            status: "failed",
+            workKind: "cc",
+            error: msg,
+            enqueuedAt: Date.now(),
+        }, sessionId);
         backgroundJobRegistry.finish(jobId, { status: "failed", finalText: msg });
     });
 }
@@ -163,7 +252,12 @@ export function makeDriveAgentTool(runner = defaultRunner, fixedCli, options = {
         const requestedCwd = normalizeCwdPath(rawRequestedCwd);
         if (!prompt)
             return "Error: prompt is required";
-        const cli = fixedCli ?? (args.cli === "codex" ? "codex" : args.cli === "claude" || args.cli === undefined ? "claude" : "invalid");
+        const cli = fixedCli ??
+            (args.cli === "codex"
+                ? "codex"
+                : args.cli === "claude" || args.cli === undefined
+                    ? "claude"
+                    : "invalid");
         if (cli === "invalid")
             return `Error: unknown cli "${String(args.cli)}" (expected "claude" or "codex")`;
         const resumeSessionId = typeof args.resumeSessionId === "string" ? args.resumeSessionId : undefined;
@@ -202,9 +296,25 @@ export function makeDriveAgentTool(runner = defaultRunner, fixedCli, options = {
             args.permissionMode === "bypassPermissions"
             ? args.permissionMode
             : "bypassPermissions";
+        const resolvedAttachmentPaths = resolveAttachmentPaths(args.attachmentPaths, cwd);
+        if (resolvedAttachmentPaths.error)
+            return `Error: ${resolvedAttachmentPaths.error}`;
+        const attachmentPaths = resolvedAttachmentPaths.paths;
+        const promptWithAttachments = appendAttachmentPrompt(prompt, attachmentPaths);
+        const imagePaths = cli === "codex"
+            ? attachmentPaths.filter((path) => DRIVE_IMAGE_EXTS.has(extname(path).toLowerCase()))
+            : [];
         const cliName = cli === "codex" ? "Codex" : "Claude Code";
         const label = `DriveAgent(${cli}): ${prompt.slice(0, 40)}`;
-        const runOpts = { cli, prompt, resumeSessionId, cwd, permissionMode, signal: ctx?.signal ?? argSignal(args) };
+        const runOpts = {
+            cli,
+            prompt: promptWithAttachments,
+            resumeSessionId,
+            cwd,
+            permissionMode,
+            signal: ctx?.signal ?? argSignal(args),
+            imagePaths,
+        };
         const foregroundHandoffMs = options.foregroundHandoffMs ?? DRIVE_AGENT_FOREGROUND_HANDOFF_MS;
         const isWritableRun = permissionMode !== "default";
         // Background by default (these tasks are typically long). Only an explicit
@@ -232,7 +342,9 @@ export function makeDriveAgentTool(runner = defaultRunner, fixedCli, options = {
                 resumeNote,
                 `已在后台启动 ${cliName}（jobId ${tracked.jobId}）。完成后会通知你结果，无需轮询。`,
                 tracked.warning,
-            ].filter(Boolean).join("\n");
+            ]
+                .filter(Boolean)
+                .join("\n");
         }
         const run = startRun(runner, runOpts);
         const result = await waitForForegroundOrHandoff(run, foregroundHandoffMs);
@@ -250,7 +362,9 @@ export function makeDriveAgentTool(runner = defaultRunner, fixedCli, options = {
                 resumeNote,
                 `${cliName} foreground run exceeded ${foregroundHandoffMs}ms; moved it to background (jobId ${tracked.jobId}). Completion will notify this session, so do not poll.`,
                 tracked.warning,
-            ].filter(Boolean).join("\n");
+            ]
+                .filter(Boolean)
+                .join("\n");
         }
         const r = result.kind === "completed" ? result.result : await run;
         recordSuccessfulSession(sessionStore, cli, cwd, r);
@@ -269,14 +383,19 @@ export const driveClaudeCodeToolDef = {
     name: "DriveClaudeCode",
     description: "(Alias of DriveAgent with cli:claude.) Delegate a task to the external Claude Code CLI " +
         "(drives `claude` for one turn). Prefer DriveAgent for new calls; this name is kept for " +
-        "compatibility. " + driveAgentToolDef.description,
+        "compatibility. " +
+        driveAgentToolDef.description,
     inputSchema: {
         type: "object",
         properties: {
             // intentionally omit `cli` — this alias is always claude
             prompt: driveAgentToolDef.inputSchema.properties.prompt,
-            resumeSessionId: { type: "string", description: "Existing CC session id to resume (keeps context). Omit for a fresh session." },
+            resumeSessionId: {
+                type: "string",
+                description: "Existing CC session id to resume (keeps context). Omit for a fresh session.",
+            },
             cwd: driveAgentToolDef.inputSchema.properties.cwd,
+            attachmentPaths: driveAgentToolDef.inputSchema.properties.attachmentPaths,
             permissionMode: driveAgentToolDef.inputSchema.properties.permissionMode,
             background: driveAgentToolDef.inputSchema.properties.background,
         },

package/dist/tool-system/builtin/index.d.ts

@@ -19,13 +19,18 @@ import type { ToolVisibilityContext } from "../context.js";
  * registry 会把它放进 ToolResult.contentBlocks。可选的 `result` 字段是给
  * transcript / 摘要用的纯文本镜像。沙箱执行类工具(Bash 等)可返回
  * `{ result, sandbox }`,registry 把 sandbox 透传到 ToolResult.sandbox 供 UI 显示。
+ * 敏感结果可返回 `{ result, sensitive, displayResult, transcriptResult }`;
+ * `result` 仅供当前模型轮使用,显示/持久化路径必须使用占位字段。
  */
 export type BuiltinToolResult = string | {
     contentBlocks: import("../../types.js").ContentBlock[];
     result?: string;
 } | {
     result: string;
-    sandbox: import("../../types.js").ToolResult["sandbox"];
+    sandbox?: import("../../types.js").ToolResult["sandbox"];
+    sensitive?: boolean;
+    displayResult?: string;
+    transcriptResult?: string;
 };
 export type BuiltinToolFn = (args: Record<string, unknown>, ctx?: import("../context.js").ToolContext) => Promise<BuiltinToolResult>;
 export type BuiltinToolGuard = (ctx: ToolVisibilityContext) => boolean;
@@ -41,5 +46,5 @@ export declare const BUILTIN_TOOLS: BuiltinTool[];
  * Keyed by the tool's `name` (must match the toolDef name).
  */
 export declare const BUILTIN_TOOL_GUARDS: Map<string, BuiltinToolGuard>;
-/** UseCredential is available when the cwd's CredentialStore has ≥1 credential. */
-export declare function isUseCredentialAvailable(cwd: string): boolean;
+/** UseCredential is available when the cwd's credential metadata has ≥1 entry. */
+export declare function isUseCredentialAvailable(cwd: string, settingsScope?: import("../../settings/manager.js").SettingsScope): boolean;

package/dist/tool-system/builtin/index.js

@@ -39,9 +39,9 @@ import { cancelGoalToolDef, cancelGoalTool } from "./cancel-goal.js";
 import { addMarketplaceToolDef, addMarketplaceTool } from "./add-marketplace.js";
 import { bashOutputToolDef, bashOutputTool, killShellToolDef, killShellTool, listShellsToolDef, listShellsTool, } from "./background-shell-tools.js";
 import { browserObserveToolDef, browserObserveTool, browserActToolDef, browserActTool, browserNavigateToolDef, browserNavigateTool, } from "./browser-tools.js";
-import { useCredentialToolDef, useCredentialTool } from "../../credentials/use-credential-tool.js";
+import { useCredentialToolDef, useCredentialBuiltinTool, } from "../../credentials/use-credential-tool.js";
 import { injectCredentialToolDef, injectCredentialTool, isInjectCredentialAvailable, } from "../../credentials/inject-credential-tool.js";
-import { CredentialStore } from "../../credentials/store.js";
+import { credentialAccessScope, getCredentialAccess } from "../../credentials/access.js";
 export const BUILTIN_TOOLS = [
     {
         definition: {
@@ -69,7 +69,7 @@ export const BUILTIN_TOOLS = [
         definition: {
             ...editModelCatalogToolDef,
             source: "builtin",
-            permissionDefault: "ask", // writes user config — confirm before each write
+            permissionDefault: "ask", // UI hint; default classifier fallback confirms writes.
             isReadOnly: false,
             isConcurrencySafe: false, // serializes writes to the single catalog file
         },
@@ -444,6 +444,7 @@ export const BUILTIN_TOOLS = [
             isReadOnly: false,
             isConcurrencySafe: false,
             timeoutMs: DRIVE_AGENT_TOOL_TIMEOUT_MS,
+            pathPolicy: [{ kind: "arg", arg: "attachmentPaths", operation: "read" }],
         },
         execute: driveAgentTool,
     },
@@ -457,6 +458,7 @@ export const BUILTIN_TOOLS = [
             isReadOnly: false,
             isConcurrencySafe: false,
             timeoutMs: DRIVE_AGENT_TOOL_TIMEOUT_MS,
+            pathPolicy: [{ kind: "arg", arg: "attachmentPaths", operation: "read" }],
         },
         execute: driveClaudeCodeTool,
     },
@@ -650,7 +652,7 @@ export const BUILTIN_TOOLS = [
     },
     // Browser automation — 3 semantic tools driving the in-app webview via the
     // BrowserBridge (CDP). All serial on one webview (isConcurrencySafe:false).
-    // browser_observe is read-only. browser_act is permissionDefault "allow"; its
+    // browser_observe is read-only. browser_act declares a UI hint of allow; its
     // sensitive actions (click/type/select) are escalated to "ask" by a preset
     // PermissionRule keyed on argsPattern { action } (see preset/index.ts §4.6) —
     // so one tool carries per-action gating. Sensitive-action + domain-whitelist
@@ -671,7 +673,7 @@ export const BUILTIN_TOOLS = [
         definition: {
             ...browserActToolDef,
             source: "builtin",
-            permissionDefault: "allow", // per-action gating via preset rule (argsPattern.action)
+            permissionDefault: "allow", // UI hint; per-action execution gating is the preset rule.
             isReadOnly: false,
             isConcurrencySafe: false,
             timeoutMs: 30_000, // the wait action internally bounds; give RPC headroom
@@ -689,8 +691,8 @@ export const BUILTIN_TOOLS = [
         execute: browserNavigateTool,
     },
     // ─── Credentials: AI 取用已存凭证(token/link/cookie) ──────────
-    // permissionDefault:"allow" —— 取用审批由工具内部的 CredentialUseGate 负责
-    // (默认问/本会话记住/全自动),不走工具级权限层,避免双重弹窗。
+    // permissionDefault:"allow" 是展示/声明 hint；取用审批由工具内部的
+    // CredentialUseGate 负责(默认问/本会话记住/全自动),避免双重弹窗。
     // 读取凭证库本身不写文件(cookie 物化成临时 cookies.txt 是用完即弃的副产物)。
     {
         definition: {
@@ -700,10 +702,10 @@ export const BUILTIN_TOOLS = [
             isReadOnly: true,
             isConcurrencySafe: true,
         },
-        execute: useCredentialTool,
+        execute: useCredentialBuiltinTool,
     },
     // InjectCredential:把 cookie 凭证注入内置浏览器(恢复登录态)。审批由工具内部
-    // CredentialUseGate 负责(逐条 autoInjectByAI),故 permissionDefault:"allow"。
+    // CredentialUseGate 负责(逐条 autoInjectByAI),permissionDefault:"allow" 仅作展示 hint。
     // 改浏览器登录态有副作用 → 非 read-only。
     {
         definition: {
@@ -730,17 +732,17 @@ export const BUILTIN_TOOL_GUARDS = new Map([
     // of the tool list (and the context) for the common no-credentials case,
     // matching the spec's "quiet when empty" intent (true ToolSearch-deferral for
     // builtins isn't wired in the engine).
-    [useCredentialToolDef.name, (ctx) => isUseCredentialAvailable(ctx.cwd)],
+    [useCredentialToolDef.name, (ctx) => isUseCredentialAvailable(ctx.cwd, ctx.settingsScope)],
     // InjectCredential hidden until ≥1 cookie credential exists (browser injection
     // is cookie-only). Also degrades at call time if no browser bridge is wired.
     [injectCredentialToolDef.name, (ctx) => isInjectCredentialAvailable(ctx.cwd, ctx.settingsScope)],
     [completeGoalToolDef.name, (ctx) => ctx.hasGoal === true],
     [cancelGoalToolDef.name, (ctx) => ctx.hasGoal === true],
 ]);
-/** UseCredential is available when the cwd's CredentialStore has ≥1 credential. */
-export function isUseCredentialAvailable(cwd) {
+/** UseCredential is available when the cwd's credential metadata has ≥1 entry. */
+export function isUseCredentialAvailable(cwd, settingsScope) {
     try {
-        return new CredentialStore(cwd).listMasked().length > 0;
+        return getCredentialAccess().listMasked(cwd, credentialAccessScope(settingsScope)).length > 0;
     }
     catch {
         return false;

package/dist/tool-system/builtin/powershell.d.ts

@@ -5,7 +5,10 @@
  * centralized in {@link safeSpawn}; this file only carries the pwsh /
  * powershell.exe selection + the PowerShell-specific output formatting.
  */
-import type { ToolDefinition } from "../../types.js";
+import type { ToolDefinition, ToolResult } from "../../types.js";
 import type { ToolContext } from "../context.js";
 export declare const powershellToolDef: ToolDefinition;
-export declare function powershellTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
+export declare function powershellTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string | {
+    result: string;
+    sandbox: ToolResult["sandbox"];
+}>;

package/dist/tool-system/builtin/powershell.js

@@ -28,6 +28,10 @@ export const powershellToolDef = {
     },
 };
 const PS_MAX_BUFFER = 5 * 1024 * 1024;
+const POWERSHELL_SANDBOX_MARK = { backend: "off" };
+function markPowerShellResult(result) {
+    return { result, sandbox: POWERSHELL_SANDBOX_MARK };
+}
 export async function powershellTool(args, ctx) {
     const command = args.command;
     // `??` only catches null/undefined — a non-positive timeout (0/-5) would slip
@@ -35,7 +39,7 @@ export async function powershellTool(args, ctx) {
     const rawTimeout = args.timeout;
     const timeout = typeof rawTimeout === "number" && rawTimeout > 0 ? rawTimeout : 120_000;
     if (!command.trim()) {
-        return "Error: command is required.";
+        return markPowerShellResult("Error: command is required.");
     }
     // Determine PowerShell executable.
     const psCmd = process.platform === "win32" ? "powershell.exe" : "pwsh";
@@ -52,19 +56,19 @@ export async function powershellTool(args, ctx) {
         signal: ctx?.signal,
     });
     if (result.aborted) {
-        return wasAbortedBeforeStart
+        return markPowerShellResult(wasAbortedBeforeStart
             ? "PowerShell aborted before starting."
-            : "PowerShell aborted by signal.";
+            : "PowerShell aborted by signal.");
     }
     if (result.timedOut) {
-        return `PowerShell timed out after ${timeout}ms`;
+        return markPowerShellResult(`PowerShell timed out after ${timeout}ms`);
     }
     if (result.spawnFailed) {
-        return `PowerShell spawn error: ${result.error ?? "unknown error"}`;
+        return markPowerShellResult(`PowerShell spawn error: ${result.error ?? "unknown error"}`);
     }
     if (result.exitCode !== 0) {
         const out = [result.stdout.trim(), result.stderr.trim()].filter(Boolean).join("\n");
-        return `PowerShell error:\n${out || `exit code ${result.exitCode}`}`;
+        return markPowerShellResult(`PowerShell error:\n${out || `exit code ${result.exitCode}`}`);
     }
-    return result.stdout.trim() || "(no output)";
+    return markPowerShellResult(result.stdout.trim() || "(no output)");
 }

package/dist/tool-system/builtin/read.js

@@ -1,9 +1,10 @@
 /**
  * Built-in Read file tool.
  */
-import { readFile, stat } from "node:fs/promises";
-import { existsSync } from "node:fs";
-import { isAbsolute, resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { readFile, stat, open } from "node:fs/promises";
+import { createReadStream, existsSync } from "node:fs";
+import { extname, isAbsolute, relative, resolve, sep } from "node:path";
 import { fileCache } from "./file-cache.js";
 import { toLf } from "./eol.js";
 export const readToolDef = {
@@ -11,7 +12,8 @@ export const readToolDef = {
     description: "Read a file from the local filesystem. Returns the file content with line numbers. " +
         "By default reads up to 2000 lines from the beginning. " +
         "Use offset and limit to read specific portions of large files. " +
-        "For large files, consider using Grep first to find the relevant lines.\n\n" +
+        "For images and binary files, returns path/metadata instead of raw bytes. " +
+        "For large text files, consider using Grep first to find the relevant lines.\n\n" +
         "Do NOT re-read a file you just edited to verify — Edit/Write would have errored " +
         "if the change failed.\n" +
         "Do NOT re-read a file (or the same range of a file) you've already read earlier in " +
@@ -28,6 +30,15 @@ export const readToolDef = {
     },
 };
 const MAX_CONTENT_CHARS = 200_000;
+const LARGE_TEXT_BYTES = 5 * 1024 * 1024;
+const SAMPLE_BYTES = 8192;
+const IMAGE_EXT_MIME = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+};
 export async function readTool(args, ctx) {
     const rawPath = args.file_path;
     if (!rawPath)
@@ -40,8 +51,21 @@ export async function readTool(args, ctx) {
         // Get file info first
         const fileInfo = await stat(filePath);
         const sizeKB = Math.round(fileInfo.size / 1024);
+        const sample = await readSample(filePath, Math.min(fileInfo.size, SAMPLE_BYTES));
+        const binary = detectBinary(filePath, sample);
+        if (binary) {
+            const sha256 = await sha256File(filePath);
+            return formatBinaryReadResult({
+                filePath,
+                cwd,
+                size: fileInfo.size,
+                sha256,
+                mime: binary.mime,
+                isImage: binary.kind === "image",
+            });
+        }
         // Skip binary or excessively large files
-        if (fileInfo.size > 5 * 1024 * 1024) {
+        if (fileInfo.size > LARGE_TEXT_BYTES) {
             return `Error: File is too large (${sizeKB}KB). Use Grep to search for specific content, or provide offset and limit to read a portion.`;
         }
         // Try cache first, fall back to disk read
@@ -79,3 +103,88 @@ export async function readTool(args, ctx) {
         return `Error reading file: ${err.message}`;
     }
 }
+async function readSample(filePath, length) {
+    if (length <= 0)
+        return Buffer.alloc(0);
+    const handle = await open(filePath, "r");
+    try {
+        const buffer = Buffer.alloc(length);
+        const { bytesRead } = await handle.read(buffer, 0, length, 0);
+        return buffer.subarray(0, bytesRead);
+    }
+    finally {
+        await handle.close();
+    }
+}
+function detectBinary(filePath, sample) {
+    const imageMime = detectImageMime(filePath, sample);
+    if (imageMime)
+        return { kind: "image", mime: imageMime };
+    if (sample.length === 0)
+        return null;
+    if (sample.includes(0))
+        return { kind: "binary" };
+    try {
+        new TextDecoder("utf-8", { fatal: true }).decode(sample);
+    }
+    catch {
+        return { kind: "binary" };
+    }
+    let controls = 0;
+    for (const byte of sample) {
+        if (byte < 32 && byte !== 9 && byte !== 10 && byte !== 12 && byte !== 13)
+            controls += 1;
+    }
+    return controls > Math.max(8, sample.length * 0.01) ? { kind: "binary" } : null;
+}
+function detectImageMime(filePath, sample) {
+    if (sample.length >= 8 &&
+        sample[0] === 0x89 &&
+        sample[1] === 0x50 &&
+        sample[2] === 0x4e &&
+        sample[3] === 0x47 &&
+        sample[4] === 0x0d &&
+        sample[5] === 0x0a &&
+        sample[6] === 0x1a &&
+        sample[7] === 0x0a) {
+        return "image/png";
+    }
+    if (sample.length >= 3 && sample[0] === 0xff && sample[1] === 0xd8 && sample[2] === 0xff) {
+        return "image/jpeg";
+    }
+    const header = sample.subarray(0, 12).toString("ascii");
+    if (header.startsWith("GIF87a") || header.startsWith("GIF89a"))
+        return "image/gif";
+    if (header.startsWith("RIFF") && header.slice(8, 12) === "WEBP")
+        return "image/webp";
+    return IMAGE_EXT_MIME[extname(filePath).toLowerCase()];
+}
+async function sha256File(filePath) {
+    const hash = createHash("sha256");
+    for await (const chunk of createReadStream(filePath)) {
+        hash.update(chunk);
+    }
+    return hash.digest("hex");
+}
+function formatBinaryReadResult(input) {
+    const path = displayPath(input.filePath, input.cwd);
+    const lines = [
+        input.isImage ? "Image file (not displayed by Read)." : "Binary file (not displayed by Read).",
+        `Path: ${path}`,
+        `Absolute path: ${input.filePath}`,
+        ...(input.mime ? [`MIME: ${input.mime}`] : []),
+        `Size: ${input.size} bytes`,
+        `SHA-256: ${input.sha256}`,
+    ];
+    if (input.isImage) {
+        lines.push(`Use view_image({ path: "${path}" }) to inspect pixels.`);
+    }
+    return lines.join("\n");
+}
+function displayPath(filePath, cwd) {
+    const rel = relative(cwd, filePath);
+    if (rel && rel !== ".." && !rel.startsWith(`..${sep}`)) {
+        return sep === "\\" ? rel.replace(/\\/g, "/") : rel;
+    }
+    return filePath;
+}

package/dist/tool-system/builtin/view-image.js

@@ -41,6 +41,11 @@ export const viewImageToolDef = {
                 type: "number",
                 description: "Image history number N from an earlier [image #N, already provided] placeholder.",
             },
+            detail: {
+                type: "string",
+                enum: ["low", "standard", "high"],
+                description: "Optional image detail preference. Accepted for compatibility; current providers use the runtime image detail default.",
+            },
         },
     },
 };
@@ -52,6 +57,10 @@ export async function viewImageTool(args, ctx) {
     if (hasPath === hasImageNumber) {
         return "Error: provide exactly one of path or imageNumber";
     }
+    const detail = args.detail;
+    if (detail !== undefined && detail !== "low" && detail !== "standard" && detail !== "high") {
+        return "Error: detail must be one of low, standard, high";
+    }
     if (hasImageNumber) {
         if (typeof rawImageNumber !== "number" ||
             !Number.isSafeInteger(rawImageNumber) ||

package/dist/tool-system/executor.d.ts

@@ -1,7 +1,7 @@
 /**
  * Tool executor — orchestrates permission checks, hooks, and execution.
  */
-import type { ToolCall, ToolResult, Message } from "../types.js";
+import type { ToolCall, ToolResult } from "../types.js";
 import type { HookRegistry } from "../hooks/registry.js";
 import { ToolRegistry } from "./registry.js";
 import { PermissionClassifier } from "./permission.js";
@@ -42,9 +42,5 @@ export declare class ToolExecutor {
     private resolvePolicyOperation;
     private enforceDeclaredPathPolicy;
     private resolvePathPolicyTargets;
-    /**
-     * Convert tool results into Message entries for the transcript.
-     */
-    resultsToMessages(toolCalls: ToolCall[], results: ToolResult[]): Message[];
 }
 export {};