codeshark-cli 0.1.1 → 0.1.4

package/dist/repl.js

@@ -5,9 +5,11 @@ import { runAgent } from "./agent.js";
 import { ProviderError, errorMessage } from "./provider/types.js";
 import { runSetup } from "./setup.js";
 import { loadConfig, modelLabel, saveConfig } from "./config.js";
-import { DEFAULT_MODEL_ID, MODELS, findModel } from "./models.js";
+import { DEFAULT_MODEL_ID, MODELS, RETIRED_MODELS, findModel, isRetiredModel } from "./models.js";
 import { launchKeysPage } from "./keysPage.js";
-const PROMPT = "🦈 ";
+import { defaultSystemPrompt } from "./system.js";
+import { modelAvailability, modelAvailabilityReason } from "./modelAvailability.js";
+const PROMPT = "> ";
 function replClosed(rl) {
     return Boolean(rl.closed);
 }
@@ -15,16 +17,23 @@ function briefArgs(args) {
     const s = JSON.stringify(args);
     return s.length > 90 ? s.slice(0, 90) + "…" : s;
 }
+async function approveToolCall(rl, call, signal) {
+    rl.resume();
+    const answer = await rl.question(`\n  Approve ${call.name}(${briefArgs(call.args)})? [y/N]: `, { signal });
+    return answer.trim().toLowerCase() === "y" || answer.trim().toLowerCase() === "yes";
+}
 function printHelp() {
     console.log([
         "",
         bold("  CodeShark commands"),
         dim("    /help            show this help"),
         dim("    /model           show the active model and the full catalog"),
-        dim("    /model <name>    switch model, e.g. /model glm or /model kimi-k3"),
+        dim("    /model <name>    switch model, e.g. /model glm or /model deepseek"),
         dim("    /keys            open the password-protected local API key page"),
         dim("    /key-status      show masked key status in the terminal"),
         dim("    /setup           guided setup wizard (providers / keys)"),
+        dim("    /plan            switch to read-only planning mode"),
+        dim("    /build           switch to implementation mode"),
         dim("    /clear           clear the screen"),
         dim("    /quit            exit (Ctrl+C also works)"),
         "",
@@ -38,11 +47,21 @@ export function printModelInfo() {
     console.log(bold("  Model catalog"));
     for (const m of MODELS) {
         const active = m.id === (findModel(cfg.model ?? "")?.id ?? DEFAULT_MODEL_ID);
-        const marker = active ? hex("#4ade80", "●") : dim("○");
-        console.log(`    ${marker} ${m.label.padEnd(28)} ${dim(m.context.padEnd(5))} ${m.notes}`);
+        const status = modelAvailability(m.id);
+        const marker = status === "available" ? hex("#4ade80", "●") : status === "unavailable" ? hex("#f87171", "✗") : dim("○");
+        const note = status === "unavailable" ? `Unavailable${modelAvailabilityReason(m.id) ? ` — ${modelAvailabilityReason(m.id)}` : ""}` : m.notes;
+        console.log(`    ${marker} ${m.label.padEnd(28)} ${dim(m.context.padEnd(5))} ${status === "unavailable" ? hex("#f87171", note) : note}`);
+    }
+    for (const m of RETIRED_MODELS) {
+        console.log(`    ${hex("#f87171", "✗")} ${m.label.padEnd(28)} ${dim(m.context.padEnd(5))} ${hex("#f87171", "Unavailable — removed by provider")}`);
+    }
+    const cfgModel = loadConfig().model;
+    if (cfgModel && isRetiredModel(cfgModel)) {
+        console.log(hex("#f87171", `  ✗ Saved model "${cfgModel}" is unavailable. Using ${findModel(DEFAULT_MODEL_ID)?.label ?? DEFAULT_MODEL_ID}.`));
     }
     console.log("");
-    console.log(dim("  Switch with: /model <name>   e.g. /model glm, /model kimi, /model gpt"));
+    console.log(dim("  Switch with: /model <name>"));
+    console.log(dim("  Names: gpt, deepseek, minimax, glm, gemini-3.6, sarvam, gpt-oss, nemotron"));
     console.log("");
 }
 export function switchModel(query) {
@@ -59,6 +78,16 @@ export function switchModel(query) {
         console.log(dim("  Available: " + MODELS.map((m) => m.label).join(", ")));
         return;
     }
+    if (entry.available === false) {
+        console.log(hex("#f87171", `  ✗ ${entry.label} is unavailable — it was removed by the provider.`));
+        console.log(dim("  Choose one of the currently available models listed by /model."));
+        return;
+    }
+    if (modelAvailability(entry.id) === "unavailable") {
+        console.log(hex("#f87171", `  ✗ ${entry.label} is currently unavailable.`));
+        console.log(dim(`  ${modelAvailabilityReason(entry.id) ?? "The boot health check failed."}`));
+        return;
+    }
     cfg.model = entry.id;
     saveConfig(cfg);
     console.log(`  ${hex("#4ade80", "✓")} Switched to ${bold(entry.label)} ${dim(`(${entry.context} context)`)}`);
@@ -73,28 +102,37 @@ function printKeys() {
     const or = Boolean(cfg.openrouterApiKey ?? process.env.OPENROUTER_API_KEY);
     const nv = Boolean(cfg.nvidiaApiKey ?? process.env.NVIDIA_API_KEY);
     const gm = Boolean(cfg.geminiApiKey ?? process.env.GEMINI_API_KEY);
-    console.log(`    ${ur ? hex("#4ade80", "✓") : dim("○")} UnoRouter    ${ur ? dim("(configured)") : dim("(not set)")}  → https://unorouter.com/en/tokens ${dim("key: shown once")}`);
+    console.log(`    ${ur ? hex("#4ade80", "✓") : dim("○")} Model API    ${ur ? dim("(configured)") : dim("(not set)")}  ${dim("key: shown once")}`);
     console.log(`    ${or ? hex("#4ade80", "✓") : dim("○")} OpenRouter   ${or ? dim("(configured)") : dim("(not set)")}  → https://openrouter.ai/keys  ${dim("key: sk-or-v1-…")}`);
     console.log(`    ${nv ? hex("#4ade80", "✓") : dim("○")} NVIDIA NIM   ${nv ? dim("(configured)") : dim("(not set)")}  → https://build.nvidia.com   ${dim("key: nvapi-…")}`);
     console.log(`    ${gm ? hex("#4ade80", "✓") : dim("○")} Google AI Studio ${gm ? dim("(configured)") : dim("(not set)")}  → https://aistudio.google.com/apikey ${dim("key: AIza…")}`);
     console.log("");
     console.log(dim("  Add one: run /setup, or paste it into ~/.codeshark.json like:"));
-    console.log(dim('    { "unorouterApiKey": "ur-…", "openrouterApiKey": "sk-or-v1-…" }'));
-    console.log(dim("  Or set env vars: UNOROUTER_API_KEY, OPENROUTER_API_KEY, NVIDIA_API_KEY, GEMINI_API_KEY"));
+    console.log(dim('    { "unorouterApiKey": "your-key", "openrouterApiKey": "sk-or-v1-…" }'));
+    console.log(dim("  Or set the provider environment variables configured for your deployment."));
     console.log("");
 }
 export async function startRepl(opts) {
     const rl = createInterface({ input, output });
     rl.setPrompt(PROMPT);
     let history = [];
-    console.log(dim("  Type a message and press Enter. /help for commands · Ctrl+C to quit."));
+    let mode = "build";
+    let busy = false;
+    let controller;
+    console.log(dim("  Type a message and press Enter. /help for commands · Ctrl+C cancels a request; press again to quit."));
     rl.prompt();
     rl.on("SIGINT", () => {
+        if (controller && !controller.signal.aborted) {
+            controller.abort(new Error("Request cancelled."));
+            return;
+        }
         console.log("");
-        console.log(dim("Bye! 🦈"));
+        console.log(dim("Bye!"));
         process.exit(0);
     });
     rl.on("line", async (raw) => {
+        if (busy)
+            return;
         const line = raw.trim();
         if (!line) {
             if (!replClosed(rl))
@@ -103,53 +141,75 @@ export async function startRepl(opts) {
         }
         // Commands
         if (line.startsWith("/")) {
-            const [cmd, ...rest] = line.slice(1).split(/\s+/);
-            switch (cmd) {
-                case "help":
-                case "h":
-                    printHelp();
-                    break;
-                case "model":
-                case "m":
-                    if (rest.length)
-                        switchModel(rest.join(" "));
-                    else
-                        printModelInfo();
-                    break;
-                case "keys":
-                case "key":
-                    console.log(dim(`  Opening local key vault… ${await launchKeysPage()}`));
-                    console.log(dim("  The browser page asks for a password before showing keys."));
-                    break;
-                case "key-status":
-                case "keystatus":
-                    printKeys();
-                    break;
-                case "clear":
-                    history = [];
-                    process.stdout.write("\u001b[2J\u001b[H");
-                    break;
-                case "setup":
-                    rl.pause();
-                    await runSetup();
+            busy = true;
+            try {
+                const [cmd, ...rest] = line.slice(1).split(/\s+/);
+                switch (cmd) {
+                    case "help":
+                    case "h":
+                        printHelp();
+                        break;
+                    case "model":
+                    case "m":
+                        if (rest.length)
+                            switchModel(rest.join(" "));
+                        else
+                            printModelInfo();
+                        break;
+                    case "keys":
+                    case "key":
+                        console.log(dim(`  Opening local key vault… ${await launchKeysPage()}`));
+                        console.log(dim("  The browser page asks for a password before showing keys."));
+                        break;
+                    case "key-status":
+                    case "keystatus":
+                        printKeys();
+                        break;
+                    case "clear":
+                        history = [];
+                        process.stdout.write("\u001b[2J\u001b[H");
+                        break;
+                    case "setup":
+                        rl.pause();
+                        await runSetup();
+                        rl.resume();
+                        console.log(dim("  Provider chain reloaded."));
+                        break;
+                    case "plan":
+                        mode = "plan";
+                        console.log(dim("  Plan mode enabled. The agent will inspect and explain without changing files."));
+                        break;
+                    case "build":
+                        mode = "build";
+                        console.log(dim("  Build mode enabled. The agent can implement changes and verify them."));
+                        break;
+                    case "quit":
+                    case "exit":
+                    case "q":
+                        console.log(dim("Bye!"));
+                        process.exit(0);
+                        break;
+                    default:
+                        console.log(dim(`  Unknown command "${cmd}". Try /help.`));
+                }
+            }
+            catch (error) {
+                console.log(hex("#f87171", "  " + errorMessage(error)));
+            }
+            finally {
+                busy = false;
+                if (!replClosed(rl))
                     rl.resume();
-                    console.log(dim("  Provider chain reloaded."));
-                    break;
-                case "quit":
-                case "exit":
-                case "q":
-                    console.log(dim("Bye! 🦈"));
-                    process.exit(0);
-                    break;
-                default:
-                    console.log(dim(`  Unknown command "${cmd}". Try /help.`));
             }
             if (!replClosed(rl))
                 rl.prompt();
             return;
         }
         // Agent run
-        rl.pause();
+        busy = true;
+        controller = new AbortController();
+        // Keep input active so Ctrl+C can cancel while the model is working.
+        rl.resume();
         console.log("");
         const events = {
             onText: (delta) => process.stdout.write(delta),
@@ -159,10 +219,16 @@ export async function startRepl(opts) {
             onDebug: (msg) => console.log(dim(msg)),
         };
         try {
+            const cfg = loadConfig();
             const result = await runAgent(line, {
                 clients: opts.getClients(),
                 registry: opts.registry,
                 cwd: opts.cwd,
+                systemPrompt: cfg.systemPrompt ?? defaultSystemPrompt(opts.cwd, mode),
+                readOnly: mode === "plan",
+                maxIterations: cfg.maxIterations,
+                approveToolCall: (call) => approveToolCall(rl, call, controller?.signal),
+                signal: controller.signal,
                 debug: opts.debug,
                 initialMessages: history,
             }, events);
@@ -190,6 +256,8 @@ export async function startRepl(opts) {
                 console.log(hex("#f87171", `  ✗ ${errorMessage(e)}`));
             }
         }
+        busy = false;
+        controller = undefined;
         console.log("");
         if (!replClosed(rl)) {
             rl.resume();

package/dist/setup.js

@@ -2,9 +2,11 @@ import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import { exec } from "node:child_process";
 import { bold, dim, hex } from "./ansi.js";
-import { configPath, hasApiKey, loadConfig, saveConfig } from "./config.js";
+import { DEFAULT_GEMINI_MODEL, configPath, hasApiKey, loadConfig, saveConfig } from "./config.js";
 import { createUnoRouterClient } from "./provider/unorouter.js";
 import { createGeminiClient } from "./provider/gemini.js";
+import { createNvidiaClient } from "./provider/nvidia.js";
+import { createOpenRouterClient } from "./provider/openrouter.js";
 import { ollamaAvailable } from "./provider/ollama.js";
 import { MODELS } from "./models.js";
 import { errorMessage } from "./provider/types.js";
@@ -79,7 +81,7 @@ function saveDone(cfg) {
 export async function runSetup() {
     const rl = createInterface({ input, output });
     try {
-        await runSetupFlow(loadConfig(), rl, { title: "🦈  CodeShark setup" });
+        await runSetupFlow(loadConfig(), rl, { title: "CodeShark setup" });
     }
     finally {
         rl.close();
@@ -92,7 +94,7 @@ export async function runSetup() {
 export async function runSetupFlow(cfg, rl, opts = {}) {
     const askSecret = secretQuestion(rl);
     console.log("");
-    console.log(bold(hex("#d96b43", opts.title ?? "🦈  CodeShark setup")));
+    console.log(bold(hex("#d96b43", opts.title ?? "CodeShark setup")));
     console.log("");
     console.log(bold("  How do you want to talk to the models?"));
     console.log(dim("    [1] Shared CodeShark gateway — zero setup. No key on this computer;"));
@@ -126,17 +128,57 @@ export async function runSetupFlow(cfg, rl, opts = {}) {
         console.log("");
         return true;
     }
-    // Choice 2 — the user's own key (typed into the terminal, never echoed).
-    console.log(bold("  Step 1 — UnoRouter key (unlocks all 5 models)"));
-    console.log(dim("    1. Open https://unorouter.com/en/tokens  (sign up with Discord/GitHub, no card)"));
-    console.log(dim("    2. Create an API key on the Tokens page — it is shown exactly once — and copy it"));
+    // Choice 2 — choose which provider key to configure.
+    console.log(bold("  Choose an API provider"));
+    console.log(dim("    [1] Primary model API — eight free catalog models"));
+    console.log(dim("    [2] Gemini API"));
+    console.log(dim("    [3] NVIDIA NIM"));
+    console.log(dim("    [4] OpenRouter"));
+    console.log(dim("    [5] Cancel"));
+    const keyChoice = (await rl.question("  Choose [1-5]: ")).trim();
+    if (keyChoice === "5")
+        return false;
+    if (keyChoice === "2") {
+        const gk = await askSecret("  Paste your Gemini API key (Enter to skip): ");
+        if (!gk)
+            return false;
+        cfg.geminiApiKey = gk;
+        cfg.provider = "gemini";
+        cfg.model = DEFAULT_GEMINI_MODEL;
+        await testClient("Gemini", createGeminiClient(cfg, gk));
+        saveDone(cfg);
+        return true;
+    }
+    if (keyChoice === "3") {
+        const nk = await askSecret("  Paste your NVIDIA API key (Enter to skip): ");
+        if (!nk)
+            return false;
+        cfg.nvidiaApiKey = nk;
+        cfg.provider = "nvidia";
+        await testClient("NVIDIA", createNvidiaClient(cfg, nk));
+        saveDone(cfg);
+        return true;
+    }
+    if (keyChoice === "4") {
+        const ok = await askSecret("  Paste your OpenRouter API key (Enter to skip): ");
+        if (!ok)
+            return false;
+        cfg.openrouterApiKey = ok;
+        cfg.provider = "openrouter";
+        await testClient("OpenRouter", createOpenRouterClient(cfg, ok));
+        saveDone(cfg);
+        return true;
+    }
+    console.log(bold("  Step 1 — Model API key (unlocks all 8 free models)"));
+    console.log(dim("    1. Open the provider token page shown by your administrator"));
+    console.log(dim("    2. Create an API key — it is shown exactly once — and copy it"));
     console.log(dim("    Your key is typed hidden: it will not appear on screen."));
     openBrowser("https://unorouter.com/en/tokens");
-    const urKey = await askSecret("  Paste your UnoRouter key (Enter to skip): ");
+    const urKey = await askSecret("  Paste your model API key (Enter to skip): ");
     if (urKey) {
         cfg.unorouterApiKey = urKey;
         cfg.provider = "unorouter";
-        await testClient("UnoRouter (GLM 5.3 Flash Thinking)", createUnoRouterClient(cfg, urKey));
+        await testClient("Model provider (GLM 5.3 Flash Think Search)", createUnoRouterClient(cfg, urKey));
         await pickModel(rl, cfg);
         saveDone(cfg);
         return true;
@@ -147,7 +189,9 @@ export async function runSetupFlow(cfg, rl, opts = {}) {
     if (gk) {
         cfg.geminiApiKey = gk;
         cfg.provider = "gemini";
+        cfg.model = DEFAULT_GEMINI_MODEL;
         await testClient("Gemini", createGeminiClient(cfg, gk));
+        await pickModel(rl, cfg);
         saveDone(cfg);
         return true;
     }

package/dist/system.js

@@ -1,17 +1,35 @@
-export function defaultSystemPrompt(cwd) {
-    return `You are CodeShark, a friendly, capable coding agent running inside the user's terminal. Your mascot is a pixel-art shark.
+export function defaultSystemPrompt(cwd, mode = "build") {
+    const modeInstructions = mode === "plan"
+        ? `
+Current mode: PLAN
+- Inspect the relevant files and use read-only tools as needed.
+- Do not edit, create, delete, install, commit, or otherwise mutate anything.
+- Return a practical implementation plan with the controlling files, assumptions, risks, exact change sequence, and verification commands.`
+        : `
+Current mode: BUILD
+- Implement the user's request completely with focused edits.
+- Verify the work with the narrowest useful tests or typechecks, then review the result for regressions before reporting completion.`;
+    return `You are CodeShark, a senior software engineer working directly in the user's terminal. Your job is to produce correct, maintainable, verified results, not merely plausible suggestions.
 
 Working directory: ${cwd}
+${modeInstructions}
 
-Rules:
-- Use your tools to inspect the project before making changes. Prefer reading the relevant files over guessing.
-- For existing files, make surgical edits with edit_file (oldString must match exactly once). Use write_file only to create new files or fully replace tiny ones.
-- Use run_command for anything a shell can do: tests, builds, git status, package installs. Prefer read-only commands (git status, git diff, npm test) over destructive ones.
-- After editing code, verify it: run the typecheck/tests if the project has them, and report the result honestly.
-- Be concise. Answer in the user's language unless asked otherwise.
-- Work step by step. If a step fails, diagnose with tools and retry with a different approach.
-- Never claim you ran a command or edited a file unless you actually did through your tools.
-- When the task is complete, call the "finish" tool with a one or two sentence summary instead of typing it as chat text.
+Engineering protocol:
+1. Translate the request into concrete acceptance criteria. Resolve ambiguity from nearby code, tests, and configuration before guessing.
+2. Inspect first. Read the owning implementation, its call sites, and the nearest relevant tests. Keep exploration focused on the requested behavior.
+3. State a short working hypothesis internally, then make the smallest change that tests it. Preserve existing APIs, conventions, and unrelated user changes.
+4. Use the tools deliberately: read/search to gather evidence, edit_file for precise existing-file changes, write_file for new files, and run_command for validation. Stay inside the working directory.
+5. Treat tool results as evidence. Check paths, types, return values, error cases, platform behavior, and security boundaries. Never invent output.
+6. Validate after changes. Prefer a focused test first, then the project's typecheck/build/test command when relevant. If validation fails, diagnose the failure, repair the same slice, and rerun it.
+7. Before finishing, review the changed behavior for regressions, missing edge cases, stale documentation, and unnecessary scope. Report remaining risk or unavailable checks honestly.
+
+Safety and quality rules:
+- Never edit, delete, install, commit, push, or run a mutating command without the user's approval prompt being accepted.
+- Never weaken folder boundaries, secret handling, approval checks, or dangerous-command protections to make a task pass.
+- Do not expose secrets, fabricate citations, or claim work you did not perform.
+- Do not make speculative broad refactors. Prefer a small complete fix over many clever abstractions.
+- Keep responses concise and in the user's language. Explain decisions and tradeoffs when they affect behavior.
+- When the task is complete, call the "finish" tool with a one- or two-sentence factual summary instead of repeating the whole transcript.
 
 If the user's request is a simple question that needs no tools, just answer it directly.`;
 }

package/dist/tools/files.js

@@ -19,13 +19,14 @@ function looksBinary(text) {
 }
 export const readFileTool = {
     name: "read_file",
+    readOnly: true,
     description: "Read a text file. Use offset (1-based line number) and limit (number of lines) to read large files in windows. Output is line-numbered.",
     inputSchema: {
         type: "object",
         properties: {
             path: { type: "string", description: "Path to the file, absolute or relative to the working directory." },
             offset: { type: "integer", description: "1-based starting line. Default 1." },
-            limit: { type: "integer", description: "Max lines to return. Default: whole file." },
+            limit: { type: "integer", description: "Max lines to return. Default 400." },
         },
         required: ["path"],
     },
@@ -37,14 +38,14 @@ export const readFileTool = {
         if (st.isDirectory())
             throw new Error(`${prettyPath(p, ctx.cwd)} is a directory — use list_directory instead.`);
         if (st.size > MAX_READ_BYTES) {
-            throw new Error(`File is ${Math.round(st.size / 1024 / 1024)} MB — too large to read whole. Use offset/limit to page through it.`);
+            throw new Error(`File is ${Math.round(st.size / 1024 / 1024)} MB — too large for the text reader. Use a targeted shell command to inspect it.`);
         }
         const text = readFileSync(p, "utf8");
         if (looksBinary(text))
             throw new Error(`File appears to be binary — refusing to read as text.`);
         const lines = text.split("\n");
         const start = args.offset ? Math.max(1, Number(args.offset)) : 1;
-        const end = args.limit ? Math.min(lines.length, start + Number(args.limit) - 1) : lines.length;
+        const end = Math.min(lines.length, start + Number(args.limit ?? 400) - 1);
         const body = lines
             .slice(start - 1, end)
             .map((line, i) => `${String(start + i).padStart(5)} | ${line}`)
@@ -106,7 +107,7 @@ export const editFileTool = {
             count++;
             if (idx === -1)
                 idx = hit;
-            from = hit + oldString.length;
+            from = hit + 1;
         }
         if (count === 0) {
             throw new Error(`oldString not found in ${prettyPath(p, ctx.cwd)}. It must match the file exactly — check whitespace/indentation.`);
@@ -122,6 +123,7 @@ export const editFileTool = {
 };
 export const listDirectoryTool = {
     name: "list_directory",
+    readOnly: true,
     description: "List the files and subdirectories in a directory. Directories are suffixed with '/'.",
     inputSchema: {
         type: "object",
@@ -206,33 +208,28 @@ export function globToRegExp(glob) {
     return new RegExp(re + "$");
 }
 const SKIP_DIRS = new Set(["node_modules", ".git", "dist", ".next", "target", "vendor", "__pycache__"]);
-function walkFiles(dir, out, depth) {
-    if (depth > 12)
+function* walkFiles(dir, depth) {
+    if (depth > 30)
         return;
     let entries;
     try {
-        entries = readdirSync(dir, { withFileTypes: true });
+        entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
     }
     catch {
         return;
     }
     for (const e of entries) {
-        if (out.length >= MAX_GLOB_MATCHES)
-            return;
         if (e.name.startsWith("."))
-            continue; // skip hidden
-        if (e.isDirectory()) {
-            if (SKIP_DIRS.has(e.name))
-                continue;
-            walkFiles(resolve(dir, e.name), out, depth + 1);
-        }
-        else if (e.isFile()) {
-            out.push(resolve(dir, e.name));
-        }
+            continue;
+        if (e.isDirectory() && !SKIP_DIRS.has(e.name))
+            yield* walkFiles(resolve(dir, e.name), depth + 1);
+        else if (e.isFile())
+            yield resolve(dir, e.name);
     }
 }
 export const globTool = {
     name: "glob",
+    readOnly: true,
     description: "Find files matching a glob pattern, e.g. \"src/**/*.ts\" or \"*.json\". Skips node_modules, .git, and hidden files by default.",
     inputSchema: {
         type: "object",
@@ -247,26 +244,27 @@ export const globTool = {
         if (!pattern)
             return "pattern is required.";
         const cwd = args.cwd ? resolvePath(args.cwd, ctx.cwd) : ctx.cwd;
-        const staticPrefix = pattern.slice(0, pattern.indexOf("*"));
-        const prefix = staticPrefix.split(/[\\/]/).slice(0, -1).join("/") || ".";
-        const searchRoot = resolveProjectPath(prefix, cwd);
-        if (!statSync(searchRoot, { throwIfNoEntry: false })?.isDirectory()) {
-            return `No matches for ${pattern}`;
-        }
-        const all = [];
-        walkFiles(searchRoot, all, 0);
         const rx = globToRegExp(pattern.replace(/\\/g, "/"));
-        const matches = all
-            .map((f) => relative(cwd, f).replace(/\\/g, "/"))
-            .filter((f) => rx.test(f))
-            .slice(0, MAX_GLOB_MATCHES);
+        const matches = [];
+        let truncated = false;
+        for (const file of walkFiles(cwd, 0)) {
+            const name = relative(cwd, file).replace(/\\/g, "/");
+            if (!rx.test(name))
+                continue;
+            if (matches.length === MAX_GLOB_MATCHES) {
+                truncated = true;
+                break;
+            }
+            matches.push(name);
+        }
         if (!matches.length)
             return `No matches for ${pattern}`;
-        return `${matches.length} match${matches.length === 1 ? "" : "es"} for ${pattern}:\n${matches.join("\n")}`;
+        return `${matches.length} match${matches.length === 1 ? "" : "es"} for ${pattern}:\n${matches.join("\n")}${truncated ? "\n... More matches exist; narrow the pattern." : ""}`;
     },
 };
 export const finishTool = {
     name: "finish",
+    readOnly: true,
     description: "Signal that the task is complete. Call this with a short summary of what was done instead of answering in chat text.",
     inputSchema: {
         type: "object",

package/dist/tools/registry.js

@@ -1,3 +1,6 @@
+function bounded(text) {
+    return text.length > 30_000 ? text.slice(0, 30_000) + "\n[Output truncated; narrow the request or read a smaller window.]" : text;
+}
 export class ToolRegistry {
     tools = new Map();
     add(tool) {
@@ -7,8 +10,8 @@ export class ToolRegistry {
     names() {
         return [...this.tools.keys()];
     }
-    schemas() {
-        return [...this.tools.values()].map((t) => ({
+    schemas(readOnly = false) {
+        return [...this.tools.values()].filter((t) => !readOnly || t.readOnly).map((t) => ({
             name: t.name,
             description: t.description,
             inputSchema: t.inputSchema,
@@ -23,12 +26,32 @@ export class ToolRegistry {
             };
         }
         try {
+            ctx.signal?.throwIfAborted();
+            if (ctx.readOnly && !tool.readOnly)
+                throw new Error("Plan mode is read-only. Switch to /build before changing files or running commands.");
+            if (!args || typeof args !== "object" || Array.isArray(args))
+                throw new Error("Arguments must be a JSON object.");
+            const required = tool.inputSchema.required;
+            for (const key of required ?? []) {
+                if (args[key] === undefined)
+                    throw new Error(`Missing required argument: ${key}`);
+            }
+            const properties = tool.inputSchema.properties;
+            for (const [key, value] of Object.entries(args)) {
+                const type = properties?.[key]?.type;
+                if (type === "string" && typeof value !== "string")
+                    throw new Error(`${key} must be a string.`);
+                if (type === "integer" && (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1)) {
+                    throw new Error(`${key} must be a positive integer.`);
+                }
+            }
             const content = await tool.run(args, ctx);
-            return { content: String(content), isError: false };
+            const text = String(content);
+            return { content: bounded(text), isError: false };
         }
         catch (e) {
             const msg = e instanceof Error ? e.message : String(e);
-            return { content: `Tool ${name} failed: ${msg}`, isError: true };
+            return { content: bounded(`Tool ${name} failed: ${msg}`), isError: true };
         }
     }
 }