@cjhyy/code-shell-core 0.5.0-rc.1 → 0.5.0-rc.2

package/dist/tool-system/builtin/notebook-edit.js

@@ -2,6 +2,7 @@
  * NotebookEditTool — read and edit Jupyter notebook (.ipynb) cells.
  */
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { enforcePathPolicy } from "../path-policy.js";
 export const notebookEditToolDef = {
     name: "NotebookEdit",
     description: "Edit a Jupyter notebook (.ipynb) file. Supports actions: " +
@@ -36,13 +37,19 @@ export const notebookEditToolDef = {
         required: ["file_path", "action"],
     },
 };
-export async function notebookEditTool(args) {
+export async function notebookEditTool(args, ctx) {
     const filePath = args.file_path;
     const action = args.action;
     if (!filePath)
         return "Error: file_path is required";
     if (!filePath.endsWith(".ipynb"))
         return "Error: file must be a .ipynb file";
+    // Path policy: 'read' goes through the read-side rules (sensitive paths
+    // still ask), all other actions are writes and use the stricter rules.
+    const op = action === "read" ? "read" : "write";
+    const blocked = enforcePathPolicy(filePath, op, ctx?.cwd);
+    if (blocked)
+        return blocked;
     if (action === "read") {
         if (!existsSync(filePath))
             return `Error: File not found: ${filePath}`;

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

@@ -2,5 +2,6 @@
  * Built-in Read file tool.
  */
 import type { ToolDefinition } from "../../types.js";
+import type { ToolContext } from "../context.js";
 export declare const readToolDef: ToolDefinition;
-export declare function readTool(args: Record<string, unknown>): Promise<string>;
+export declare function readTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;

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

@@ -4,6 +4,7 @@
 import { readFile, stat } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { fileCache } from "./file-cache.js";
+import { enforcePathPolicy } from "../path-policy.js";
 export const readToolDef = {
     name: "Read",
     description: "Read a file from the local filesystem. Returns the file content with line numbers. " +
@@ -26,10 +27,17 @@ export const readToolDef = {
     },
 };
 const MAX_CONTENT_CHARS = 200_000;
-export async function readTool(args) {
+export async function readTool(args, ctx) {
     const filePath = args.file_path;
     if (!filePath)
         return "Error: file_path is required";
+    // Path policy: in-workspace reads pass through; sensitive paths (~/.ssh,
+    // .env, etc.) and outside-workspace reads are refused with an explanatory
+    // error. existsSync check stays AFTER the policy gate — we don't want to
+    // probe sensitive paths' existence as a side-channel.
+    const blocked = enforcePathPolicy(filePath, "read", ctx?.cwd);
+    if (blocked)
+        return blocked;
     if (!existsSync(filePath))
         return `Error: File not found: ${filePath}`;
     try {

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

@@ -23,11 +23,17 @@ export async function sleepTool(args) {
     if (signal?.aborted)
         return "Sleep aborted.";
     await new Promise((resolve, reject) => {
-        const timer = setTimeout(resolve, seconds * 1000);
-        signal?.addEventListener("abort", () => {
+        const onAbort = () => {
             clearTimeout(timer);
             reject(new Error("Sleep aborted"));
-        });
+        };
+        const timer = setTimeout(() => {
+            // Remove the abort listener on normal completion — otherwise every Sleep
+            // call leaks a listener on the (shared, per-turn) signal.
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, seconds * 1000);
+        signal?.addEventListener("abort", onAbort, { once: true });
     }).catch(() => { });
     return `Slept for ${seconds} seconds.`;
 }

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

@@ -30,7 +30,10 @@ export const todoWriteToolDef = {
     name: "TodoWrite",
     description: "Manage the session todo list. Pass the COMPLETE list each call — there's no per-item update API, you rewrite the entire snapshot. " +
         "Use proactively for tasks with 3+ steps. Exactly one item should be in_progress at a time. " +
-        "Always provide both `content` (imperative) and `activeForm` (present continuous) so the UI can show what's happening right now.",
+        "Always provide both `content` (imperative) and `activeForm` (present continuous) so the UI can show what's happening right now. " +
+        "Skip the todo list for straightforward tasks (roughly the easiest 25%) and don't make single-step lists. " +
+        "Update the list immediately after finishing a sub-task — mark it completed in the same turn you completed it, don't batch updates across turns. " +
+        "If you change direction and a planned item will no longer be done, rewrite the list with that item dropped rather than leaving it pending; the list must reflect what you're actually going to do next.",
     inputSchema: {
         type: "object",
         properties: {

package/dist/tool-system/builtin/update-automation-memory.d.ts

@@ -0,0 +1,24 @@
+/**
+ * UpdateAutomationMemory — lets an automation (cron/scheduled) run persist a
+ * one-paragraph summary of what it did, so the NEXT run starts with context.
+ *
+ * This is a FACTORY: core must not depend on desktop's filesystem layer, so the
+ * actual persistence is supplied by an injected `sink` callback. A later task
+ * (the desktop automation runner) injects a sink that appends to the task's
+ * memory.md; this module only builds the tool + validates input.
+ */
+import type { BuiltinTool } from "./index.js";
+import type { ToolDefinition } from "../../types.js";
+/**
+ * Bare tool definition (name/description/inputSchema) — mirrors the export
+ * style of the other builtin tool defs (e.g. cron.ts). The factory below wraps
+ * this into a registry-ready RegisteredTool.
+ */
+export declare const updateAutomationMemoryToolDef: ToolDefinition;
+/**
+ * Build an UpdateAutomationMemory tool bound to a persistence `sink`.
+ *
+ * @param sink Called with the trimmed summary when a non-empty summary is given.
+ *             The caller decides where/how to persist it.
+ */
+export declare function makeUpdateAutomationMemoryTool(sink: (summary: string) => void): BuiltinTool;

package/dist/tool-system/builtin/update-automation-memory.js

@@ -0,0 +1,60 @@
+/**
+ * UpdateAutomationMemory — lets an automation (cron/scheduled) run persist a
+ * one-paragraph summary of what it did, so the NEXT run starts with context.
+ *
+ * This is a FACTORY: core must not depend on desktop's filesystem layer, so the
+ * actual persistence is supplied by an injected `sink` callback. A later task
+ * (the desktop automation runner) injects a sink that appends to the task's
+ * memory.md; this module only builds the tool + validates input.
+ */
+/**
+ * Bare tool definition (name/description/inputSchema) — mirrors the export
+ * style of the other builtin tool defs (e.g. cron.ts). The factory below wraps
+ * this into a registry-ready RegisteredTool.
+ */
+export const updateAutomationMemoryToolDef = {
+    name: "UpdateAutomationMemory",
+    description: "Persist a short memory note for this automation task so your NEXT scheduled run " +
+        "starts with context. Call this EXACTLY ONCE, at the very end of the run, with a " +
+        "concise one-paragraph summary of what you did, what you found, and anything the " +
+        "next run should know or continue (e.g. items processed, last cursor/timestamp, " +
+        "open issues). Keep it to a few sentences — it is prepended to your future prompts.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            summary: {
+                type: "string",
+                description: "A concise one-paragraph summary of this run for the next run to build on.",
+            },
+        },
+        required: ["summary"],
+    },
+};
+/**
+ * Build an UpdateAutomationMemory tool bound to a persistence `sink`.
+ *
+ * @param sink Called with the trimmed summary when a non-empty summary is given.
+ *             The caller decides where/how to persist it.
+ */
+export function makeUpdateAutomationMemoryTool(sink) {
+    return {
+        definition: {
+            ...updateAutomationMemoryToolDef,
+            source: "builtin",
+            // The summary is automation-internal bookkeeping (not user code); no prompt.
+            permissionDefault: "allow",
+            // Writes (via the injected sink), so not read-only / not concurrency-safe.
+            isReadOnly: false,
+            isConcurrencySafe: false,
+        },
+        execute: async (args) => {
+            const raw = typeof args.summary === "string" ? args.summary : "";
+            const summary = raw.trim();
+            if (!summary) {
+                return "Error: summary is required and must not be empty";
+            }
+            sink(summary);
+            return "Automation memory saved for the next run.";
+        },
+    };
+}

package/dist/tool-system/builtin/view-image.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Built-in view_image tool — 把一个本地图片文件以 base64 image ContentBlock
+ * 回传进上下文,让 vision 模型「看」它(对照 codex 的 view_image)。
+ *
+ * 典型用法:模型先写 SVG/Mermaid 并用 shell 转成 PNG,再调 view_image(png)
+ * 检查图画对没有(标签是否重叠、文字是否溢出),不对就改源再重转。
+ *
+ * 三道闸门,避免污染上下文 / 浪费 token:
+ *   1. vision gate —— 当前模型不支持视觉时不读文件,只回文字占位。
+ *   2. 格式 gate —— 只支持 png/jpeg/gif/webp(provider image 块能吃的);
+ *      svg/pdf 等回文字提示「先转 PNG」。
+ *   3. 大小 gate —— 超过 MAX_BYTES 回文字提示,不读进 base64。
+ */
+import type { ToolDefinition } from "../../types.js";
+import type { ToolContext } from "../context.js";
+import type { BuiltinToolResult } from "./index.js";
+export declare const viewImageToolDef: ToolDefinition;
+export declare function viewImageTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<BuiltinToolResult>;

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

@@ -0,0 +1,96 @@
+/**
+ * Built-in view_image tool — 把一个本地图片文件以 base64 image ContentBlock
+ * 回传进上下文,让 vision 模型「看」它(对照 codex 的 view_image)。
+ *
+ * 典型用法:模型先写 SVG/Mermaid 并用 shell 转成 PNG,再调 view_image(png)
+ * 检查图画对没有(标签是否重叠、文字是否溢出),不对就改源再重转。
+ *
+ * 三道闸门,避免污染上下文 / 浪费 token:
+ *   1. vision gate —— 当前模型不支持视觉时不读文件,只回文字占位。
+ *   2. 格式 gate —— 只支持 png/jpeg/gif/webp(provider image 块能吃的);
+ *      svg/pdf 等回文字提示「先转 PNG」。
+ *   3. 大小 gate —— 超过 MAX_BYTES 回文字提示,不读进 base64。
+ */
+import { readFile, stat } from "node:fs/promises";
+import { extname, isAbsolute, resolve } from "node:path";
+import { capabilitiesFor } from "../../llm/capabilities/index.js";
+const MAX_BYTES = 5 * 1024 * 1024; // 5MB —— vision 模型按 tile 计 token,大图无益且撑大请求
+const MEDIA_TYPES = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+};
+export const viewImageToolDef = {
+    name: "view_image",
+    description: "Load a local image file into the conversation so you can SEE it (vision). " +
+        "Use after generating or rendering an image (e.g. SVG/Mermaid → PNG) to verify it " +
+        "looks right — check for overlapping labels, clipped text, wrong layout — then fix the " +
+        "source and re-render if needed. Supports PNG/JPEG/GIF/WebP only; convert SVG/PDF to PNG " +
+        "first. Requires a vision-capable model; otherwise the image is skipped.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            path: {
+                type: "string",
+                description: "Path to the image file (absolute, or relative to the working directory).",
+            },
+        },
+        required: ["path"],
+    },
+};
+export async function viewImageTool(args, ctx) {
+    const rawPath = args.path;
+    if (typeof rawPath !== "string" || !rawPath.trim()) {
+        return "Error: path is required";
+    }
+    const cwd = ctx?.cwd ?? process.cwd();
+    const abs = isAbsolute(rawPath) ? rawPath : resolve(cwd, rawPath);
+    // 闸门 1:vision gate —— 不支持视觉就不读文件。
+    // 缺 llmConfig 时按「非视觉」处理(fail closed),对齐 DEFAULT_CAPABILITY
+    // 的保守姿态:运行时 ToolContext.llmConfig 必有,缺失只发生在测试 / 异常
+    // 装配下,此时绝不把 base64 读进上下文。
+    const supportsVision = (() => {
+        if (!ctx?.llmConfig)
+            return false;
+        const kind = (ctx.llmConfig.providerKind ?? ctx.llmConfig.provider);
+        return capabilitiesFor(kind, ctx.llmConfig.model).supportsVision;
+    })();
+    if (!supportsVision) {
+        return `[图片未加载: ${abs} —— 当前模型不支持视觉输入,已跳过。切换到 vision 模型后再 view_image。]`;
+    }
+    // 闸门 2:格式 gate
+    const ext = extname(abs).toLowerCase();
+    const mediaType = MEDIA_TYPES[ext];
+    if (!mediaType) {
+        return `[图片未加载: ${abs} —— 格式 ${ext || "(无扩展名)"} 不支持视觉预览,请先转成 PNG/JPEG。]`;
+    }
+    // 闸门 3:大小 gate(读 stat,不读全文件)
+    let size;
+    try {
+        size = (await stat(abs)).size;
+    }
+    catch (err) {
+        return `Error: 无法读取 ${abs}: ${err.message}`;
+    }
+    if (size > MAX_BYTES) {
+        const mb = (size / 1024 / 1024).toFixed(1);
+        return `[图片未加载: ${abs} —— 文件过大 (${mb} MB > 5 MB),请先压缩或缩放再 view_image。]`;
+    }
+    let buf;
+    try {
+        buf = await readFile(abs);
+    }
+    catch (err) {
+        return `Error: 无法读取 ${abs}: ${err.message}`;
+    }
+    const data = buf.toString("base64");
+    const kb = Math.round(buf.length / 1024);
+    return {
+        contentBlocks: [
+            { type: "image", source: { type: "base64", media_type: mediaType, data } },
+        ],
+        result: `[已加载图片: ${abs} (${mediaType}, ${kb} KB)]`,
+    };
+}

package/dist/tool-system/builtin/web-search.d.ts

@@ -21,5 +21,8 @@ export interface ResolvedSearchConfig {
  * the user where the value came from when debugging.
  */
 export declare function resolveSearchConfig(cwd?: string): ResolvedSearchConfig;
+export declare function isWebSearchAvailable(cwd?: string, nowMs?: number): boolean;
 export declare const webSearchToolDef: ToolDefinition;
-export declare function webSearchTool(args: Record<string, unknown>): Promise<string>;
+export declare function webSearchTool(args: Record<string, unknown>, ctx?: {
+    cwd?: string;
+}): Promise<string>;

package/dist/tool-system/builtin/web-search.js

@@ -18,7 +18,11 @@ export function resolveSearchConfig(cwd = process.cwd()) {
     let settingsKey;
     let settingsBaseUrl;
     try {
-        const merged = new SettingsManager(cwd).get();
+        // scope "full" so the USER-level ~/.code-shell/settings.json is read, not
+        // just ${cwd}/.code-shell — the search key is typically a personal/global
+        // credential. Default "project" scope would miss it (the "No search provider
+        // configured" bug, esp. for automation runs rooted at the app dir).
+        const merged = new SettingsManager(cwd, "full").get();
         const search = merged.search ?? {};
         const p = search.provider;
         if (p === "serper" || p === "tavily" || p === "searxng")
@@ -68,6 +72,33 @@ export function resolveSearchConfig(cwd = process.cwd()) {
         return { provider: "searxng", baseUrl: envSearxng, source: "env" };
     return { provider: "serper", source: "none" };
 }
+/**
+ * Tool-visibility guard: WebSearch is only useful when a search provider is
+ * configured. Mirrors the runtime check in the tool itself (source === "none"
+ * means no provider).
+ *
+ * Cached per-cwd with a short TTL: this runs on EVERY message's toolDefs
+ * assembly (engine.ts), and resolveSearchConfig reads + parses settings from
+ * disk each call. The 1s TTL collapses back-to-back reads while still picking
+ * up a newly-configured provider before the user's next message. The execution
+ * path (resolveSearchConfig) is intentionally NOT cached — only this boolean.
+ */
+const availCache = new Map();
+const AVAIL_TTL_MS = 1000;
+export function isWebSearchAvailable(cwd = process.cwd(), nowMs = Date.now()) {
+    const hit = availCache.get(cwd);
+    if (hit && nowMs - hit.at < AVAIL_TTL_MS)
+        return hit.value;
+    let value = false;
+    try {
+        value = resolveSearchConfig(cwd).source !== "none";
+    }
+    catch {
+        value = false; // unresolved config → treat as unavailable
+    }
+    availCache.set(cwd, { at: nowMs, value });
+    return value;
+}
 export const webSearchToolDef = {
     name: "WebSearch",
     description: "Search the web for information. Returns a list of search results with titles, URLs, and snippets. " +
@@ -84,12 +115,14 @@ export const webSearchToolDef = {
         required: ["query"],
     },
 };
-export async function webSearchTool(args) {
+export async function webSearchTool(args, ctx) {
     const query = args.query;
     if (!query)
         return "Error: query is required";
     const numResults = Math.min(args.num_results || 10, 20);
-    const config = resolveSearchConfig();
+    // Use the run's cwd (e.g. an automation job's project dir) so per-project
+    // settings resolve correctly; falls back to process.cwd() when absent.
+    const config = resolveSearchConfig(ctx?.cwd);
     if (config.source === "none") {
         return "Error: No search provider configured. Open desktop 设置 → 连接 to add credentials, or set SERPER_API_KEY / TAVILY_API_KEY / SEARXNG_URL.";
     }

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

@@ -2,5 +2,6 @@
  * Built-in Write file tool.
  */
 import type { ToolDefinition } from "../../types.js";
+import type { ToolContext } from "../context.js";
 export declare const writeToolDef: ToolDefinition;
-export declare function writeTool(args: Record<string, unknown>): Promise<string>;
+export declare function writeTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;

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

@@ -4,6 +4,7 @@
 import { writeFile, mkdir } from "node:fs/promises";
 import { dirname } from "node:path";
 import { fileCache } from "./file-cache.js";
+import { enforcePathPolicy } from "../path-policy.js";
 export const writeToolDef = {
     name: "Write",
     description: "Write content to a file. Creates the file if it doesn't exist, " +
@@ -17,13 +18,18 @@ export const writeToolDef = {
         required: ["file_path", "content"],
     },
 };
-export async function writeTool(args) {
+export async function writeTool(args, ctx) {
     const filePath = args.file_path;
     const content = args.content;
     if (!filePath)
         return "Error: file_path is required";
     if (content === undefined)
         return "Error: content is required";
+    // Path policy gate: deny writes to sensitive paths, refuse writes outside
+    // workspace until approved. See tool-system/path-policy.ts.
+    const blocked = enforcePathPolicy(filePath, "write", ctx?.cwd);
+    if (blocked)
+        return blocked;
     try {
         await mkdir(dirname(filePath), { recursive: true });
         await writeFile(filePath, content, "utf-8");

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

@@ -82,6 +82,8 @@ export interface SubAgentSpawnRequest {
      * the parent's appendSystemPrompt (current behavior).
      */
     appendSystemPrompt?: string;
+    /** True for read-only reviewer/researcher children; tunes investigation guard reminders. */
+    readOnlySession?: boolean;
 }
 export interface SubAgentSpawner {
     /** Run a sub-agent synchronously and return its text output. */
@@ -181,6 +183,16 @@ export interface ToolContext {
      * `settings.disabledPlugins` by Engine.run().
      */
     disabledPlugins?: string[];
+    /**
+     * Builtin tool names the project's capabilityOverrides marked `off` for
+     * this cwd. Engine.run() already HIDES these from the LLM-visible tool
+     * list, but the model can still NAME a hidden builtin (hallucinated, or
+     * remembered from an earlier turn when it was visible). The executor reads
+     * this set and rejects such a call — turning `off` into a real execution
+     * gate, not just a prompt-visibility filter. Empty/undefined for
+     * sub-agents and no-cwd contexts (same as readBuiltinOverride).
+     */
+    disabledBuiltins?: Set<string>;
 }
 /**
  * Per-Engine container that produces a fresh ToolContext on demand.

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

@@ -40,7 +40,6 @@ export declare class ToolExecutor {
     isConcurrencySafe(toolName: string): boolean;
     executeSingle(callIn: ToolCall): Promise<ToolResult>;
     private isReadOnlyBashCommand;
-    executeAll(calls: ToolCall[]): Promise<ToolResult[]>;
     /**
      * Convert tool results into Message entries for the transcript.
      */

package/dist/tool-system/executor.js

@@ -5,6 +5,7 @@ import { setMaxListeners } from "node:events";
 import { logger as rootLogger, getCurrentSid } from "../logging/logger.js";
 import { recordToolCall, recordToolResult } from "../logging/session-recorder.js";
 import { validateToolArgs } from "./validation.js";
+import { PLAN_MODE_ALLOWED_TOOLS } from "./plan-mode-allowlist.js";
 // A1 hardening: hooks must never promote a non-`allow` classifier
 // decision to `allow`. They may otherwise adjust the decision freely
 // (e.g. tighten `allow` to `deny`/`ask`, or relax `deny` to `ask` to
@@ -83,22 +84,41 @@ export class ToolExecutor {
         // Local `call` so we can rewrite args via pre_tool_use updatedInput
         // without mutating the caller's object.
         let call = callIn;
+        // 0. Abort fast-path: if the run signal is already aborted, return a
+        // synthetic error result WITHOUT running pre_tool_use hooks, the
+        // permission classifier, or the handler. registry.executeTool also checks
+        // abort, but only after this method has paid for all the per-tool
+        // hook/permission round-trips. For an aborted sub-agent whose turn queued
+        // a batch of tools (e.g. 10 Reads), this collapses the whole batch
+        // instantly instead of round-tripping each one — part of the sub-agent
+        // leak fix that keeps an aborted child from burning work post-abort.
+        if (this.signal?.aborted) {
+            return {
+                id: call.id,
+                toolName: call.toolName,
+                error: `Tool aborted before execution: ${call.toolName}`,
+                isError: true,
+            };
+        }
+        // 0. Capability override: a builtin the project marked `off` is HIDDEN from
+        // the model's tool list (engine.ts applyBuiltinOverrideVisibility), but the
+        // model can still NAME it (hallucination, or a remembered earlier turn). The
+        // registry still holds the tool, so without a gate here it would execute.
+        // Reject it the same way plan mode rejects a disallowed tool — return an
+        // error result, never run the handler.
+        if (this.toolCtx?.disabledBuiltins?.has(call.toolName)) {
+            return {
+                id: call.id,
+                toolName: call.toolName,
+                error: `Tool ${call.toolName} is disabled by this project's capability override and cannot be used. Do NOT retry this tool call.`,
+                isError: true,
+            };
+        }
         // 0. Plan mode: only allow read-only tools — no file writes at all
         if (this.toolCtx?.planMode) {
-            const allowedInPlan = new Set([
-                "EnterPlanMode",
-                "ExitPlanMode",
-                "Read",
-                "Glob",
-                "Grep",
-                "WebSearch",
-                "WebFetch",
-                "AskUserQuestion",
-                "Agent",
-                "ToolSearch",
-                "TodoWrite",
-            ]);
-            if (!allowedInPlan.has(call.toolName)) {
+            // Shared with engine.ts's tool-visibility filter so the set the model
+            // SEES and the set the executor RUNS can't drift (they had).
+            if (!PLAN_MODE_ALLOWED_TOOLS.has(call.toolName)) {
                 if (call.toolName === "Bash" && this.isReadOnlyBashCommand(call.args)) {
                     // Read-only bash is fine
                 }
@@ -447,32 +467,6 @@ export class ToolExecutor {
         }
         return false;
     }
-    async executeAll(calls) {
-        const results = [];
-        // Separate safe (concurrent) and unsafe (sequential) tools
-        const safe = [];
-        const unsafe = [];
-        for (const call of calls) {
-            const tool = this.registry.getTool(call.toolName);
-            if (tool?.isConcurrencySafe) {
-                safe.push(call);
-            }
-            else {
-                unsafe.push(call);
-            }
-        }
-        // Execute safe tools concurrently
-        if (safe.length > 0) {
-            const safeResults = await Promise.all(safe.map((c) => this.executeSingle(c)));
-            results.push(...safeResults);
-        }
-        // Execute unsafe tools sequentially
-        for (const call of unsafe) {
-            const result = await this.executeSingle(call);
-            results.push(result);
-        }
-        return results;
-    }
     /**
      * Convert tool results into Message entries for the transcript.
      */

package/dist/tool-system/investigation-guard.d.ts

@@ -21,6 +21,7 @@ export interface GuardDecision {
     block?: string;
     prepend?: string;
 }
+export type InvestigationGuardPolicy = "normal" | "soft" | "read-only-review";
 export declare class InvestigationGuard {
     private readHistory;
     private consecutiveReads;
@@ -35,8 +36,10 @@ export declare class InvestigationGuard {
      * be killed by the guard — it should still get the signal to change
      * strategy, but the tool call goes through.
      */
-    private softMode;
+    private policy;
+    private readOnlyReviewBudgetReminderShown;
     setSoftMode(soft: boolean): void;
+    setPolicy(policy: InvestigationGuardPolicy): void;
     preToolCheck(call: ToolCall): GuardDecision | undefined;
     noteText(text: string | undefined): void;
     noteToolResult(_call: ToolCall, _result: ToolResult): void;

package/dist/tool-system/investigation-guard.js

@@ -38,9 +38,13 @@ export class InvestigationGuard {
      * be killed by the guard — it should still get the signal to change
      * strategy, but the tool call goes through.
      */
-    softMode = false;
+    policy = "normal";
+    readOnlyReviewBudgetReminderShown = false;
     setSoftMode(soft) {
-        this.softMode = soft;
+        this.policy = soft ? "soft" : "normal";
+    }
+    setPolicy(policy) {
+        this.policy = policy;
     }
     preToolCheck(call) {
         const tool = call.toolName;
@@ -68,7 +72,7 @@ export class InvestigationGuard {
                 `Re-reading the same content will not produce new information. ` +
                 `Switch strategy: run a command with side effects (Bash, debug log, repro), make a code change, or ask the user a specific question. ` +
                 `If you genuinely need this content, summarize what you already know about it from prior reads instead of re-fetching.`;
-            if (this.softMode) {
+            if (this.policy !== "normal") {
                 // Soft mode (headless): deliver the same signal as a prepend so the
                 // model still sees it, but allow the tool call to proceed. Hard-
                 // blocking an unattended `code-shell run …` would dead-end the task
@@ -84,6 +88,14 @@ export class InvestigationGuard {
                 `Re-reading rarely yields new information. After this result, change strategy (Bash side-effect, edit, or ask user) rather than reading further.</system-reminder>`);
         }
         if (this.consecutiveReads > READ_BUDGET) {
+            if (this.policy === "read-only-review") {
+                if (!this.readOnlyReviewBudgetReminderShown) {
+                    this.readOnlyReviewBudgetReminderShown = true;
+                    prependParts.push(`<system-reminder>Investigation guard: ${this.consecutiveReads} consecutive read-only calls during an explicit read-only review. ` +
+                        `Continue only if each read is adding new evidence, and surface a concise status update when useful.</system-reminder>`);
+                }
+                return prependParts.length ? { prepend: prependParts.join("\n") } : undefined;
+            }
             prependParts.push(`<system-reminder>Investigation guard: ${this.consecutiveReads} consecutive read-only calls with no action taken. ` +
                 `Per coding.md, change strategy now — make a code change, run a command with side effects, or ask the user.</system-reminder>`);
         }
@@ -106,6 +118,10 @@ export class InvestigationGuard {
         this.turnHasSideEffect = false;
         if (wasSilent >= SILENT_TURN_BUDGET && turnNumber !== this.lastReminderSilent) {
             this.lastReminderSilent = turnNumber;
+            if (this.policy === "read-only-review") {
+                return (`<system-reminder>Investigation guard: you have taken ${wasSilent} consecutive turns of read-only investigation ` +
+                    `without any text update to the user. Surface a brief status update with what you have confirmed, ruled out, and will inspect next.</system-reminder>`);
+            }
             return (`<system-reminder>Investigation guard: you have taken ${wasSilent} consecutive turns of read-only investigation ` +
                 `without any text update to the user or side-effecting action. ` +
                 `Either surface a status update (what have you ruled out, what's your current hypothesis?), ` +