@pentoshi/clai 0.12.0 → 1.0.0

package/dist/agent/runner.js

@@ -19,12 +19,25 @@ import { ensureProviderConfigured } from "../commands/providers.js";
 import { rememberThinkingFromText, renderThinkingSummary, } from "../ui/thinking.js";
 import { renderMarkdown, indentAndWrapText } from "../ui/markdown.js";
 import { startThinkingSpinner } from "../ui/spinner.js";
+import { safeCwd } from "../os/cwd.js";
 import { analyzeTask } from "./task-analyzer.js";
 import { LoopGuard } from "./loop-guard.js";
+import { createPlan, loadPlan, savePlan, markTask, } from "../store/plan.js";
+import { renderPlanChecklist, renderPlanSidePane } from "../ui/plan-pane.js";
+/** Render the plan as a right-side pane on wide terminals, else inline. */
+function renderPlanForTerminal(plan) {
+    const cols = process.stdout.columns ?? 0;
+    const side = process.stdout.isTTY
+        ? renderPlanSidePane(plan, cols)
+        : undefined;
+    return side ?? renderPlanChecklist(plan);
+}
 export function createSessionPolicy() {
     return {
         allow: new Set(),
         pentestAuthorized: { value: false },
+        sessionId: `sess-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`,
+        planApproved: { value: false },
     };
 }
 function tryParseCall(raw) {
@@ -139,6 +152,147 @@ export function parseToolCall(text, options = {}) {
     }
     return undefined;
 }
+// Argument keys that the built-in tools accept. Used to recognize when a
+// model emitted a bare args object (e.g. {"path":"file.pdf"}) — intending a
+// tool call but forgetting the {"name","args"} wrapper and the ```tool fence.
+const TOOL_ARG_KEYS = new Set([
+    "command",
+    "path",
+    "paths",
+    "url",
+    "query",
+    "target",
+    "pattern",
+    "tool",
+    "tools",
+    "files",
+    "content",
+    "calls",
+    "record",
+    "ports",
+    "profile",
+    "id",
+    "lang",
+    "dpi",
+    "psm",
+    "recursive",
+    "oldText",
+    "newText",
+    "expectedReplacements",
+    "goal",
+    "tasks",
+    "taskId",
+    "state",
+    "method",
+    "body",
+    "headers",
+    "maxBytes",
+    "maxResults",
+    "cwd",
+    "name",
+    "concurrency",
+]);
+/**
+ * Strip a single wrapping ```json / ``` fence (if any) and return the inner
+ * text trimmed. Leaves un-fenced text unchanged.
+ */
+function stripLoneFence(text) {
+    const fenced = text
+        .trim()
+        .match(/^```[a-zA-Z]*\s*\n?([\s\S]*?)\n?```$/);
+    return (fenced?.[1] ?? text).trim();
+}
+/**
+ * When a model means to call a tool but emits ONLY a bare JSON object —
+ * either a proper {"name","args"} that the strict matchers missed, or a bare
+ * args object like {"path":"file.pdf"} with the wrapper/fence dropped — this
+ * recognizes it. Returns:
+ *   - { call } when the object is a complete {name, args} tool call, or
+ *   - { argsOnly: true } when it looks like a bare args object (so the caller
+ *     can nudge the model to re-emit a properly named, fenced tool call).
+ * Returns undefined for anything that is plainly a normal prose/JSON answer.
+ */
+export function recognizeBareToolJson(text) {
+    const inner = stripLoneFence(text);
+    // Must be a single JSON object spanning the whole (de-fenced) output.
+    if (!inner.startsWith("{") || !inner.endsWith("}"))
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(inner);
+    }
+    catch {
+        return undefined;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return undefined;
+    }
+    const obj = parsed;
+    // Complete {name, args} call the earlier matchers didn't catch (e.g. not
+    // anchored to end-of-string). Recover it directly.
+    const direct = tryParseCall(inner);
+    if (direct)
+        return { call: direct };
+    // Bare args object: every key is a known tool-arg key, and it carries at
+    // least one identifying arg. Don't treat huge/odd objects as tool args.
+    const keys = Object.keys(obj);
+    if (keys.length === 0 || keys.length > 6)
+        return undefined;
+    const allKnown = keys.every((key) => TOOL_ARG_KEYS.has(key));
+    if (allKnown)
+        return { argsOnly: true };
+    return undefined;
+}
+/**
+ * Detect an opened-but-unparseable tool call. This happens when the model's
+ * output is truncated by the token limit mid-JSON: we see the ```tool fence
+ * (or a bare {"name":"...","args" prefix) open, but parseToolCall returns
+ * undefined because the JSON never closed. Without this, the broken block
+ * leaks to the screen as a "final answer" and the requested action (e.g. a
+ * multi-file fs.writeMany scaffold) silently never runs.
+ */
+export function looksLikeTruncatedToolCall(text) {
+    // An opened ```tool fence with no closing fence.
+    const openFence = /```tool\s*\n?/i.test(text);
+    const closeFence = /```tool[\s\S]*?```/i.test(text);
+    if (openFence && !closeFence)
+        return true;
+    // A tool-call JSON object that started but whose braces never balanced.
+    const jsonStart = text.search(/\{\s*"name"\s*:\s*"[A-Za-z][\w.]*"\s*,\s*"args"/);
+    if (jsonStart >= 0) {
+        const slice = text.slice(jsonStart);
+        let depth = 0;
+        let inString = false;
+        let escaped = false;
+        let balanced = false;
+        for (const ch of slice) {
+            if (escaped) {
+                escaped = false;
+                continue;
+            }
+            if (ch === "\\") {
+                escaped = true;
+                continue;
+            }
+            if (ch === '"')
+                inString = !inString;
+            if (inString)
+                continue;
+            if (ch === "{")
+                depth += 1;
+            else if (ch === "}") {
+                depth -= 1;
+                if (depth === 0) {
+                    balanced = true;
+                    break;
+                }
+            }
+        }
+        if (!balanced)
+            return true;
+    }
+    return false;
+}
 /** Extract the text before the tool call block for display purposes */
 function textBeforeToolCall(text) {
     const patterns = [
@@ -174,8 +328,20 @@ function formatToolArgs(call) {
         return String(call.args.target ?? "");
     if (call.name === "fs.read" || call.name === "fs.write")
         return String(call.args.path ?? "");
+    if (call.name === "fs.writeMany") {
+        const files = Array.isArray(call.args.files) ? call.args.files : [];
+        const names = files
+            .map((f) => f && typeof f === "object"
+            ? String(f.path ?? "")
+            : "")
+            .filter(Boolean);
+        const preview = names.slice(0, 4).join(", ");
+        return `${names.length} file(s)${preview ? `: ${preview}${names.length > 4 ? ", …" : ""}` : ""}`;
+    }
     if (call.name === "fs.search")
         return String(call.args.pattern ?? "");
+    if (call.name === "image.ocr" || call.name === "pdf.read")
+        return String(call.args.path ?? "");
     if (call.name === "http.fetch" || call.name === "web.fetch")
         return String(call.args.url ?? "");
     if (call.name === "web.search")
@@ -183,7 +349,7 @@ function formatToolArgs(call) {
     if (call.name === "pkg.install")
         return String(call.args.tool ?? "");
     if (call.name === "fs.list")
-        return String(call.args.path ?? process.cwd());
+        return String(call.args.path ?? safeCwd());
     return JSON.stringify(call.args);
 }
 const VOLATILE_SIGNAL_RE = /\b(?:current(?:ly)?|latest|newest|today|now|right now|live|recent|breaking|news|release[sd]?|version|prices?|stocks?|market|rates?|weather|forecast|elections?|results?|rankings?|standings?|stats?|cve|advis(?:ory|ories)|vulnerabilit(?:y|ies))\b/i;
@@ -192,6 +358,44 @@ const ROLE_OF_ENTITY_RE = /\b(?:cm|chief\s+minister|prime\s+minister|president|g
 const EXPLICIT_WEB_LOOKUP_RE = /\b(?:search\s+(?:the\s+)?(?:web|internet|online)|look\s*up|google|verify\s+(?:online|on\s+the\s+web)|check\s+(?:online|the\s+web|internet))\b/i;
 const STATIC_DISAMBIGUATION_RE = /\b(?:stand\s+for|stands\s+for|meaning|definition|define|abbreviation|centimeters?|centimetres?)\b/i;
 const LOCAL_RUNTIME_RE = /\b(?:current\s+(?:directory|dir|cwd|working\s+directory|folder|path|user|shell|process(?:es)?|branch|git\s+branch|network|ip|interfaces?|working\s+tree)|pwd|whoami)\b/i;
+// Signals that the current turn is (or continues) a coding / scaffolding
+// task. These are intentionally broad — over-budgeting a build is cheap
+// (the loop still stops as soon as the model gives a final answer) while
+// under-budgeting silently truncates a half-built project.
+const BUILD_TASK_RE = /\b(?:build|create|scaffold|generate|make|set\s*up|setup|bootstrap|init(?:ialize)?|implement|add|write|develop|code|refactor|migrate|convert|wire\s*up|integrate)\b[\s\S]{0,80}\b(?:app|application|project|site|website|web\s*app|server|api|service|component|page|module|feature|cli|script|library|package|frontend|backend|fullstack|game|bot|dashboard|form|endpoint|database|schema|test|tests|suite)\b/i;
+const BUILD_STACK_RE = /\b(?:react|next(?:\.?js)?|vue|svelte|angular|vite|webpack|express|fastify|nest(?:js)?|django|flask|fastapi|rails|laravel|spring|node(?:\.?js)?|typescript|tailwind|redux|prisma|mongoose|graphql|docker|kubernetes)\b/i;
+// Short continuation prompts that, on their own, carry no build signal but
+// clearly mean "keep going with what we were doing".
+const CONTINUATION_RE = /^(?:do\s+it|build\s+it|build\s+fully|build\s+it\s+fully|go\s+ahead|continue|proceed|keep\s+going|finish(?:\s+it)?|complete(?:\s+it)?|yes|ok(?:ay)?|make\s+it|run\s+it|next|on\s+your\s+own|build\s+(?:fully\s+)?on\s+your\s+own)\b/i;
+const INCOMPLETE_RE = /\b(?:not\s+complete|incomplete|isn'?t\s+(?:done|complete|working|finished)|doesn'?t\s+work|still\s+(?:broken|missing|failing)|missing\s+(?:files?|parts?)|finish\s+(?:the|it)|complete\s+(?:the|it))\b/i;
+/**
+ * Decide whether this turn should get a generous step budget because it is
+ * a multi-file build, a continuation of one, or a "it's not done yet" nudge.
+ * Looks at the current prompt first, then falls back to the most recent
+ * user/assistant turns so a terse follow-up inherits the build context.
+ */
+export function looksLikeBuildTask(prompt, history) {
+    const text = prompt.replace(/\s+/g, " ").trim();
+    if (BUILD_TASK_RE.test(text) ||
+        BUILD_STACK_RE.test(text) ||
+        CONTINUATION_RE.test(text) ||
+        INCOMPLETE_RE.test(text)) {
+        return true;
+    }
+    // Inspect recent history: if the conversation was already about building
+    // something, treat a terse follow-up as part of that build.
+    if (history && history.length > 0) {
+        const recent = history.slice(-6);
+        for (const msg of recent) {
+            if (msg.role !== "user" && msg.role !== "assistant")
+                continue;
+            const h = msg.content.replace(/\s+/g, " ");
+            if (BUILD_TASK_RE.test(h) || BUILD_STACK_RE.test(h))
+                return true;
+        }
+    }
+    return false;
+}
 export function requiresFreshWebSearch(prompt) {
     const text = prompt.replace(/\s+/g, " ").trim();
     if (!text)
@@ -332,6 +536,132 @@ async function confirmToolExecution(call, autoConfirm, session) {
         default: true,
     });
 }
+/** Build the system-context block describing the session's active plan. */
+function planContextMessage(plan, approved) {
+    const lines = [];
+    lines.push(`ACTIVE PLAN for this session (goal: ${plan.goal}, status: ${plan.status}):`);
+    if (plan.detail.trim())
+        lines.push(plan.detail.trim());
+    lines.push("Tasks:");
+    plan.tasks.forEach((t, i) => {
+        lines.push(`  ${i + 1}. [${t.id}] (${t.state}) ${t.title}`);
+    });
+    if (approved) {
+        lines.push("The user APPROVED this plan. Execute it task by task NOW: before starting a task call " +
+            'task.update with {"taskId":"<id>","state":"in_progress"}, do the work with real tool calls, ' +
+            'then call task.update {"taskId":"<id>","state":"done"} (or "failed"/"skipped" with a note). ' +
+            "Actually run installs and start servers — never claim something ran without a successful tool call. " +
+            "When all tasks are done, verify and give a final summary.");
+    }
+    else {
+        lines.push("This plan is NOT yet approved. If the user is refining it, update it with plan.create again. " +
+            "Do NOT execute tasks until the user runs /implement.");
+    }
+    return lines.join("\n");
+}
+/**
+ * Handle plan.create / task.update inline. These are session-scoped and
+ * persisted via the plan store so the user can view the plan (Ctrl+P) and
+ * the agent keeps it in context across the whole session.
+ */
+async function handlePlanTool(call, session, ctx) {
+    void ctx;
+    if (call.name === "plan.create") {
+        const goal = typeof call.args.goal === "string" ? call.args.goal : "";
+        const detail = typeof call.args.detail === "string" ? call.args.detail : "";
+        const kind = typeof call.args.kind === "string" ? call.args.kind : "general";
+        const rawTasks = Array.isArray(call.args.tasks) ? call.args.tasks : [];
+        const taskTitles = rawTasks
+            .map((t) => (typeof t === "string" ? t : ""))
+            .filter(Boolean);
+        if (!goal || taskTitles.length === 0) {
+            return {
+                handled: true,
+                ok: false,
+                display: chalk.red("  ✗ plan.create needs a non-empty goal and at least one task title\n"),
+                modelNote: "plan.create failed: provide a string goal and a non-empty tasks array of step titles.",
+            };
+        }
+        const plan = createPlan({
+            sessionId: session.sessionId,
+            goal,
+            detail,
+            taskTitles,
+            kind,
+        });
+        await savePlan(plan).catch(() => undefined);
+        // A freshly (re)created plan resets approval — the user must /implement.
+        session.planApproved.value = false;
+        const checklist = renderPlanForTerminal(plan);
+        const display = chalk.cyan("  ● planning\n") +
+            checklist +
+            "\n" +
+            chalk.dim("  ✦ plan created — press Ctrl+P to view it, or type /implement to approve and run it\n");
+        return {
+            handled: true,
+            ok: true,
+            display,
+            modelNote: `Plan saved with ${plan.tasks.length} task(s). STOP here and wait. ` +
+                "Do NOT start executing tasks until the user approves with /implement. " +
+                "When approved you will receive a message telling you to begin; then work task by task, " +
+                "calling task.update to mark each in_progress before and done after you finish it.",
+        };
+    }
+    // task.update
+    const plan = await loadPlan(session.sessionId).catch(() => undefined);
+    if (!plan) {
+        return {
+            handled: true,
+            ok: false,
+            display: chalk.red("  ✗ task.update: no active plan — call plan.create first\n"),
+            modelNote: "task.update failed: there is no active plan. Call plan.create first.",
+        };
+    }
+    const taskId = typeof call.args.taskId === "string" ? call.args.taskId : "";
+    const stateRaw = typeof call.args.state === "string" ? call.args.state : "";
+    const note = typeof call.args.note === "string" ? call.args.note : undefined;
+    const validStates = [
+        "pending",
+        "in_progress",
+        "done",
+        "failed",
+        "skipped",
+    ];
+    if (!validStates.includes(stateRaw)) {
+        return {
+            handled: true,
+            ok: false,
+            display: chalk.red(`  ✗ task.update: state must be one of ${validStates.join(", ")}\n`),
+            modelNote: `task.update failed: state must be one of ${validStates.join(", ")}.`,
+        };
+    }
+    const ok = markTask(plan, taskId, stateRaw, note);
+    if (!ok) {
+        const ids = plan.tasks.map((t) => t.id).join(", ");
+        return {
+            handled: true,
+            ok: false,
+            display: chalk.red(`  ✗ task.update: unknown taskId "${taskId}" (have: ${ids})\n`),
+            modelNote: `task.update failed: unknown taskId. Valid ids: ${ids}.`,
+        };
+    }
+    if (plan.status === "draft" || plan.status === "approved") {
+        plan.status = "in_progress";
+    }
+    const allDone = plan.tasks.every((t) => t.state === "done" || t.state === "skipped" || t.state === "failed");
+    if (allDone)
+        plan.status = "completed";
+    await savePlan(plan).catch(() => undefined);
+    const checklist = renderPlanForTerminal(plan);
+    return {
+        handled: true,
+        ok: true,
+        display: checklist + "\n",
+        modelNote: allDone
+            ? "Task updated. ALL tasks are now finished. Verify the result and give your final summary."
+            : "Task updated. Continue with the next pending task.",
+    };
+}
 export async function runAgentLoop(prompt, options = {}) {
     const config = getConfig();
     const maxSteps = options.maxSteps ?? 30;
@@ -345,17 +675,39 @@ export async function runAgentLoop(prompt, options = {}) {
     if (freshWebSearchRequired) {
         systemSections.push(freshnessGuardMessage());
     }
-    const fullSystemPrompt = systemSections.join("\n\n");
-    const messages = [
-        { role: "system", content: fullSystemPrompt },
-        ...(options.history ?? []),
-        { role: "user", content: prompt },
-    ];
     let provider = options.provider ?? config.defaultProvider;
     await ensureProviderConfigured(provider);
     let model = options.model ?? config.defaultModel;
     let lastAnswer = "";
     const session = options.session ?? createSessionPolicy();
+    // ── Active plan context ────────────────────────────────────────────
+    // If this session already has a plan, inject it so the model keeps it in
+    // context. When the user has approved it (via /implement) we instruct the
+    // agent to execute task by task; otherwise the agent should refine/wait.
+    const activePlan = await loadPlan(session.sessionId).catch(() => undefined);
+    if (activePlan) {
+        systemSections.push(planContextMessage(activePlan, session.planApproved.value));
+    }
+    const fullSystemPrompt = systemSections.join("\n\n");
+    const userMessage = { role: "user", content: prompt };
+    if (options.images && options.images.length > 0) {
+        userMessage.images = options.images;
+    }
+    const messages = [
+        { role: "system", content: fullSystemPrompt },
+        ...(options.history ?? []),
+        userMessage,
+    ];
+    const recoveryUserMessage = (content) => {
+        const message = { role: "user", content };
+        if (options.images && options.images.length > 0) {
+            // Some OpenAI-compatible gateways/models attend most strongly to the
+            // latest user turn. Keep the image attached on recovery nudges so a
+            // thinking-only retry does not degrade into OCR/tool guessing.
+            message.images = options.images;
+        }
+        return message;
+    };
     // Track recent tool calls to detect models stuck in a loop calling the
     // same tool with the same arguments over and over (e.g. pentest.recon
     // called 3× on the same target without summarizing).
@@ -363,18 +715,59 @@ export async function runAgentLoop(prompt, options = {}) {
     // Track consecutive thinking-only responses so we can nudge the model
     // to actually act instead of silently returning an empty answer.
     let emptyVisibleRetries = 0;
+    // Track tool calls truncated by the token limit so we can ask the model
+    // to retry in smaller pieces instead of leaking broken JSON as an answer.
+    let truncatedToolRetries = 0;
+    // Track bare-args JSON tool calls (missing the {name,args} wrapper / fence)
+    // so we can nudge the model to re-emit a proper fenced call a few times
+    // before giving up, instead of leaking the JSON as a final answer.
+    let bareToolJsonRetries = 0;
     // For volatile live-info prompts, make one corrective pass if a model
     // ignores the freshness guard and tries to answer from stale memory.
     let sawFreshWebSearch = false;
     let freshnessRetryUsed = false;
-    // ── Complexity-based step limit (no hardcoded plans) ──────────────
+    // ── Step budget ───────────────────────────────────────────────────
+    // The budget governs how many *productive* steps (a tool execution or a
+    // final answer) the agent may take. Recovery iterations — nudging a model
+    // that only produced thinking, asking it to re-emit a malformed tool call,
+    // a freshness retry, or a loop-guard summary — do NOT consume this budget;
+    // they get a separate hard ceiling so a wedged model can't spin forever.
+    //
+    // Complexity is a coarse signal from prompt length, but short follow-up
+    // prompts ("do it", "build fully on your own", "app is not complete") in
+    // the middle of a multi-file build must NOT be capped like a one-shot
+    // lookup — that was the reason a React scaffold stopped half-built after
+    // 10 steps. We bump the budget when the prompt (or recent history) looks
+    // like a build/scaffold or a continuation of one.
     const analysis = analyzeTask(prompt);
-    const dynamicMaxSteps = analysis.complexity === "simple"
-        ? 10
+    const hasHistory = (options.history?.length ?? 0) > 0;
+    const buildLike = looksLikeBuildTask(prompt, options.history);
+    let stepBudget = analysis.complexity === "simple"
+        ? 15
         : analysis.complexity === "standard"
-            ? 20
+            ? 30
             : maxSteps;
-    for (let step = 0; step < dynamicMaxSteps; step += 1) {
+    if (buildLike) {
+        // Scaffolding / multi-file work needs room: many file writes plus a
+        // verify/build step. Continuation prompts ("do it") inherit this too.
+        stepBudget = Math.max(stepBudget, maxSteps);
+    }
+    else if (hasHistory) {
+        // A follow-up to an ongoing task should never be capped tighter than a
+        // standard one-shot, even if it's only a couple of words.
+        stepBudget = Math.max(stepBudget, 30);
+    }
+    // Hard ceiling on total loop iterations (productive + recovery) so a model
+    // stuck emitting only thinking or malformed calls can't loop indefinitely.
+    const maxIterations = stepBudget * 3;
+    let productiveSteps = 0;
+    let step = -1;
+    for (let iteration = 0; iteration < maxIterations; iteration += 1) {
+        // `step` is the productive-step index (used for display + audit). It only
+        // advances when the previous iteration actually executed a tool.
+        step = productiveSteps;
+        if (productiveSteps >= stepBudget)
+            break;
         options.signal?.throwIfAborted();
         // Buffer LLM output so tool JSON and hidden thinking are not printed raw.
         // Status messages (rate-limit retries, fallback hints) still surface live.
@@ -392,9 +785,11 @@ export async function runAgentLoop(prompt, options = {}) {
                 temperature: 0.2,
                 // Reasoning models can spend a lot on hidden thinking; give
                 // them headroom so the visible answer / tool call isn't
-                // truncated to silence. Keep the no-thinking default lean so
-                // fast models like kimi-k2.6 respond instantly.
-                maxTokens: config.thinking?.enabled ? 8_192 : 4_096,
+                // truncated to silence. The non-thinking budget must be large
+                // enough for a multi-file fs.writeMany payload — a truncated
+                // tool-call JSON fails to parse and used to leak a broken
+                // ```tool block to the screen with no files written.
+                maxTokens: config.thinking?.enabled ? 16_384 : 8_192,
                 signal: options.signal,
                 thinking: config.thinking,
             }, (token) => {
@@ -446,12 +841,10 @@ export async function runAgentLoop(prompt, options = {}) {
                 process.stdout.write(`${renderThinkingSummary(assistantText.thinkContent)}\n`);
                 process.stdout.write(chalk.yellow("  ⚠ model produced only thinking — nudging it to take action\n"));
                 messages.push({ role: "assistant", content: completion.text });
-                messages.push({
-                    role: "user",
-                    content: "You only produced internal reasoning with no visible answer or tool call. " +
-                        "You MUST either call a tool using the ```tool format or provide your final answer. " +
-                        "Do NOT just think — take action NOW.",
-                });
+                messages.push(recoveryUserMessage("You only produced internal reasoning with no visible answer or tool call. " +
+                    "You MUST either call a tool using the ```tool format or provide your final answer. " +
+                    "If images are attached, inspect them directly for visual details (text, colors, layout, spacing, style) instead of using OCR unless explicitly needed. " +
+                    "Do NOT just think — take action NOW."));
                 continue;
             }
             // Exhausted retries — fall through to the normal empty-answer path
@@ -461,10 +854,42 @@ export async function runAgentLoop(prompt, options = {}) {
             // Reset the counter on any successful visible output.
             emptyVisibleRetries = 0;
         }
-        const call = parseToolCall(assistantText.visible, {
+        let call = parseToolCall(assistantText.visible, {
             strict: getConfig().parserStrict,
         });
+        // Recovery: the model meant to call a tool but emitted a bare JSON object
+        // with no ```tool fence — either a complete {name,args} the strict
+        // matchers missed (recover it directly), or just an args object like
+        // {"path":"file.pdf"} with the wrapper dropped (nudge a retry below so
+        // the requested action runs instead of the JSON leaking as the answer).
+        let bareArgsOnly = false;
+        let recoveredFromBareJson = false;
+        if (!call) {
+            const bare = recognizeBareToolJson(assistantText.visible);
+            if (bare?.call) {
+                call = bare.call;
+                recoveredFromBareJson = true;
+                process.stdout.write(chalk.dim("  ℹ recovered an unfenced tool call from bare JSON\n"));
+            }
+            else if (bare?.argsOnly) {
+                bareArgsOnly = true;
+            }
+        }
         if (!call) {
+            if (bareArgsOnly) {
+                bareToolJsonRetries += 1;
+                if (bareToolJsonRetries <= 3) {
+                    process.stdout.write(chalk.yellow("  ⚠ tool call missing its name/fence — asking the model to re-emit a proper ```tool block\n"));
+                    messages.push({ role: "assistant", content: assistantText.visible });
+                    messages.push(recoveryUserMessage("Your previous message was a bare JSON args object with no tool name and no ```tool fence, so NOTHING ran. " +
+                        "Reply with ONLY a fenced ```tool block of the form " +
+                        '`{"name": "<tool>", "args": { ... }}`. For example, to read a PDF:\n' +
+                        '```tool\n{"name":"pdf.read","args":{"path":"/abs/file.pdf"}}\n```\n' +
+                        "Choose the correct tool name for the task and include those args."));
+                    continue;
+                }
+                // Exhausted retries — fall through to the normal answer path.
+            }
             // Detect the case where the model emitted sentinel-style tool-call
             // markers but the body was malformed or truncated. Printing those
             // raw tokens looks like a crash to the user — instead, ask the
@@ -472,15 +897,33 @@ export async function runAgentLoop(prompt, options = {}) {
             if (/<\|tool_call(?:s_section)?_begin\|>|<\|tool_call_argument_begin\|>/i.test(assistantText.visible)) {
                 process.stdout.write(chalk.yellow("  ⚠ tool call was malformed or cut off — asking the model to retry in JSON form\n"));
                 messages.push({ role: "assistant", content: assistantText.visible });
-                messages.push({
-                    role: "user",
-                    content: "Your previous tool call was malformed or truncated. " +
-                        "Reply with ONLY a fenced ```tool block containing valid JSON " +
-                        'of the form `{"name": "<tool>", "args": { ... }}`. ' +
-                        "Do not use <|tool_call_begin|> markers.",
-                });
+                messages.push(recoveryUserMessage("Your previous tool call was malformed or truncated. " +
+                    "Reply with ONLY a fenced ```tool block containing valid JSON " +
+                    'of the form `{"name": "<tool>", "args": { ... }}`. ' +
+                    "Do not use <|tool_call_begin|> markers."));
                 continue;
             }
+            // Detect a tool call that opened but was cut off by the token limit
+            // (most common with a large multi-file fs.writeMany). Retrying with a
+            // nudge to split the work is far better than rendering broken JSON as
+            // a final answer and leaving the project half-created.
+            if (looksLikeTruncatedToolCall(assistantText.visible)) {
+                truncatedToolRetries += 1;
+                if (truncatedToolRetries <= 3) {
+                    process.stdout.write(chalk.yellow("  ⚠ tool call was cut off (output too long) — asking the model to retry in smaller pieces\n"));
+                    messages.push({ role: "assistant", content: assistantText.visible });
+                    messages.push({
+                        role: "user",
+                        content: "Your previous tool call was cut off before it finished — the JSON was incomplete, so NOTHING ran. " +
+                            "Retry now with a COMPLETE, valid ```tool block. " +
+                            "If it was a large fs.writeMany, split it into SMALLER batches (3-5 files per call, and keep each file's content concise) " +
+                            "so the whole JSON fits in one response. Do NOT claim any file was written until a tool call actually succeeds.",
+                    });
+                    continue;
+                }
+                // Exhausted retries — fall through so we don't loop forever, but the
+                // user at least sees the (broken) output and the stop notice.
+            }
             // Normal final-answer path: strip any stray sentinel tokens that
             // somehow leaked into prose so the answer renders cleanly.
             const cleaned = stripSentinelTokens(assistantText.visible);
@@ -513,20 +956,31 @@ export async function runAgentLoop(prompt, options = {}) {
         // telling it to summarize the results it already has.
         const loopCheck = loopGuard.shouldBlock(call.name, call.args);
         if (loopCheck.block) {
-            process.stdout.write(chalk.yellow(`  ⚠ ${call.name} was already called with the same arguments — forcing summary\n`));
+            const isWrite = call.name === "fs.write" ||
+                call.name === "fs.writeMany" ||
+                call.name === "fs.edit";
+            process.stdout.write(chalk.yellow(`  ⚠ ${call.name} was already called with the same arguments — ${isWrite ? "moving on" : "forcing summary"}\n`));
             messages.push({ role: "assistant", content: assistantText.visible });
             messages.push({
                 role: "user",
-                content: `You already called ${call.name} with the same arguments and received results. ` +
-                    "Do NOT call it again. Summarize the findings you already have and give your final answer NOW.",
+                content: isWrite
+                    ? `You already wrote that exact file with ${call.name}. It is saved. ` +
+                        "Do NOT write it again. Move on to the NEXT file or step. If every file is written, " +
+                        "verify the project (list the tree, run the build/install command) and give your final answer."
+                    : `You already called ${call.name} with the same arguments and received results. ` +
+                        "Do NOT call it again. Summarize the findings you already have and give your final answer NOW.",
             });
             continue;
         }
         if (loopCheck.reason) {
             process.stdout.write(chalk.dim(`  ℹ ${loopCheck.reason}\n`));
         }
-        // Print only non-thinking text before the tool call.
-        const beforeTool = textBeforeToolCall(assistantText.visible);
+        // Print only non-thinking text before the tool call. When the call was
+        // recovered from a bare JSON object (the whole message WAS the call),
+        // there is no prose to show — skip it so we don't echo the raw JSON.
+        const beforeTool = recoveredFromBareJson
+            ? ""
+            : textBeforeToolCall(assistantText.visible);
         if (beforeTool) {
             process.stdout.write(renderMarkdown(beforeTool) + "\n");
         }
@@ -534,6 +988,25 @@ export async function runAgentLoop(prompt, options = {}) {
             process.stdout.write(`${renderThinkingSummary(assistantText.thinkContent)}\n`);
         }
         messages.push({ role: "assistant", content: assistantText.visible });
+        // ── Plan / task tools (session-scoped, handled inline) ─────────────
+        // These don't go through the generic registry because they need the
+        // session id and mutate the live plan that the user can view (Ctrl+P).
+        if (call.name === "plan.create" || call.name === "task.update") {
+            const planResult = await handlePlanTool(call, session, {
+                loopGuard,
+                step,
+            });
+            if (planResult.handled) {
+                productiveSteps += 1;
+                loopGuard.recordAttempt(step, call.name, call.args, planResult.ok, 0);
+                process.stdout.write(planResult.display);
+                messages.push({
+                    role: "tool",
+                    content: `Tool ${call.name} result (ok=${planResult.ok}):\n${planResult.modelNote}`,
+                });
+                continue;
+            }
+        }
         const scope = await loadScope();
         const decision = classifyToolCall(call, { scope });
         await auditLog("tool.classified", {
@@ -709,6 +1182,11 @@ export async function runAgentLoop(prompt, options = {}) {
         });
         // Record the attempt in the loop guard for dedup tracking.
         loopGuard.recordAttempt(step, call.name, call.args, result.ok, result.exitCode);
+        // A tool actually executed this iteration — count it against the
+        // productive-step budget. Recovery iterations (thinking-only nudges,
+        // malformed-call retries, freshness/loop-guard prompts) reach `continue`
+        // before this point and therefore never consume the budget.
+        productiveSteps += 1;
         // ── Auto-retry on "command not found" ──────────────────────────
         // Detect missing tools and instruct the model to install + retry.
         const NOT_FOUND_RE = /command not found|ENOENT.*spawn|is not recognized/i;
@@ -717,7 +1195,9 @@ export async function runAgentLoop(prompt, options = {}) {
                 ? String(call.args.command ?? "").split(/\s+/)[0]
                 : call.name === "net.scan"
                     ? "nmap"
-                    : undefined;
+                    : call.name === "image.ocr"
+                        ? "tesseract"
+                        : undefined;
             if (cmdName) {
                 process.stdout.write(chalk.yellow(`  ⚠ ${cmdName} not found — asking model to install and retry\n`));
                 messages.push({
@@ -807,7 +1287,7 @@ export async function runAgentLoop(prompt, options = {}) {
             }
         }
     }
-    lastAnswer = `Stopped after ${dynamicMaxSteps} steps.`;
+    lastAnswer = `Stopped after ${productiveSteps} steps.`;
     process.stdout.write("  " + chalk.yellow(lastAnswer) + "\n");
     return lastAnswer;
 }