@x-code-cli/core 0.2.1 → 0.2.3

package/dist/agent/tool-execution.js

@@ -5,31 +5,13 @@ import { checkPermission } from '../permissions/index.js';
 import { truncateToolResult } from '../tools/index.js';
 import { clearProgressReporter, reportProgress } from '../tools/progress.js';
 import { getShellProvider } from '../tools/shell-provider.js';
+import { debugLog } from '../utils.js';
 import { foldShellErrorNoise } from '../utils/shell-error.js';
 import { computeEditDiff } from './diff.js';
 import { checkForLoop, recordToolCall } from './loop-guard.js';
-import { toolResultMessage } from './messages.js';
-import { makePlanFilePath, readPlan, writePlan } from './plan-storage.js';
+import { isToolErrorString, toolErrorFromUnknown, toolErrorString, toolResultMessage } from './messages.js';
+import { handleEnterPlanMode, handleExitPlanMode, handleTodoWrite } from './plan-tools.js';
 import { runSubAgent } from './sub-agents/runner.js';
-/** Walk back through state.messages and grab the most recent user
- *  message's text — used as the slug source for the plan filename. */
-function lastUserMessageText(messages) {
-    for (let i = messages.length - 1; i >= 0; i--) {
-        const m = messages[i];
-        if (m && m.role === 'user') {
-            const content = m.content;
-            if (typeof content === 'string')
-                return content;
-            if (Array.isArray(content)) {
-                return content
-                    .filter((p) => p?.type === 'text' && typeof p.text === 'string')
-                    .map((p) => p.text)
-                    .join(' ');
-            }
-        }
-    }
-    return '';
-}
 /** Count occurrences of a substring without creating intermediate arrays. */
 function countOccurrences(content, search) {
     let count = 0;
@@ -47,7 +29,7 @@ function countOccurrences(content, search) {
  *  UI can render a colored diff under the tool bullet. The diff payload is
  *  a UI-only side channel — it never lands in `state.messages` and the
  *  model only sees the short result string. */
-async function executeWriteTool(toolName, input, toolCallId, callbacks) {
+async function executeWriteTool(toolName, input, toolCallId, callbacks, signal) {
     if (toolName === 'writeFile') {
         const filePath = input.filePath;
         const content = input.content;
@@ -58,12 +40,12 @@ async function executeWriteTool(toolName, input, toolCallId, callbacks) {
         // plus permission / EISDIR edge cases (we'd error on write anyway).
         let oldContent = null;
         try {
-            oldContent = await fs.readFile(filePath, 'utf-8');
+            oldContent = await fs.readFile(filePath, { encoding: 'utf-8', signal });
         }
         catch {
             oldContent = null;
         }
-        await fs.writeFile(filePath, content, 'utf-8');
+        await fs.writeFile(filePath, content, { encoding: 'utf-8', signal });
         const isNew = oldContent === null;
         const parts = content.split('\n');
         const lineCount = content.endsWith('\n') ? parts.length - 1 : parts.length;
@@ -81,22 +63,22 @@ async function executeWriteTool(toolName, input, toolCallId, callbacks) {
         const newString = input.newString;
         const replaceAll = input.replaceAll ?? false;
         reportProgress(toolCallId, `Editing ${filePath}`);
-        const content = await fs.readFile(filePath, 'utf-8');
+        const content = await fs.readFile(filePath, { encoding: 'utf-8', signal });
         if (!replaceAll) {
             const count = countOccurrences(content, oldString);
             if (count === 0)
-                return `Error: old_string not found in ${filePath}`;
+                return toolErrorString(`old_string not found in ${filePath}`);
             if (count > 1)
-                return `Error: old_string is not unique in ${filePath} (found ${count} occurrences). Provide more context or set replaceAll: true.`;
+                return toolErrorString(`old_string is not unique in ${filePath} (found ${count} occurrences). Provide more context or set replaceAll: true.`);
         }
         const newContent = replaceAll ? content.replaceAll(oldString, newString) : content.replace(oldString, newString);
-        await fs.writeFile(filePath, newContent, 'utf-8');
+        await fs.writeFile(filePath, newContent, { encoding: 'utf-8', signal });
         const payload = computeEditDiff(filePath, content, newContent);
         if (payload && callbacks.onFileEdit)
             callbacks.onFileEdit(toolCallId, payload);
         return `File edited: ${filePath}`;
     }
-    return 'Error: unknown write tool';
+    return toolErrorString('unknown write tool');
 }
 /** Execute a shell command with streaming. */
 async function executeShell(command, timeout, signal, callbacks, toolCallId) {
@@ -145,11 +127,23 @@ async function executeShell(command, timeout, signal, callbacks, toolCallId) {
     // `string | unknown[] | Uint8Array` — we spawn with default string mode, so
     // a cast is safe, but keep a defensive fallback for non-string just in case.
     const toStr = (v) => (typeof v === 'string' ? v : '');
-    const stdout = foldShellErrorNoise(toStr(result.stdout));
-    const stderr = foldShellErrorNoise(toStr(result.stderr));
+    let stdout = foldShellErrorNoise(toStr(result.stdout));
+    let stderr = foldShellErrorNoise(toStr(result.stderr));
+    // When execa kills the child for exceeding maxBuffer, the partial
+    // output is still available in stdout/stderr. Surface a clear
+    // truncation notice so the model doesn't silently lose context.
+    const isMaxBuffer = result.isMaxBuffer ?? false;
+    if (isMaxBuffer) {
+        const INLINE_CAP = 30_000;
+        if (stdout.length > INLINE_CAP)
+            stdout = stdout.slice(0, INLINE_CAP) + '\n... [stdout truncated — exceeded buffer limit]';
+        if (stderr.length > INLINE_CAP)
+            stderr = stderr.slice(0, INLINE_CAP) + '\n... [stderr truncated — exceeded buffer limit]';
+    }
     const output = [stdout, stderr].filter(Boolean).join('\n').trim();
-    if (result.exitCode !== 0) {
-        const text = output ? `${output}\nExit code ${result.exitCode}` : `Exit code ${result.exitCode}`;
+    if (result.exitCode !== 0 || isMaxBuffer) {
+        const suffix = isMaxBuffer ? ' (output exceeded buffer limit)' : '';
+        const text = output ? `${output}\nExit code ${result.exitCode}${suffix}` : `Exit code ${result.exitCode}${suffix}`;
         return { output: text, isError: true };
     }
     return { output: output || 'Done', isError: false };
@@ -164,360 +158,369 @@ function pushToolResult(state, callbacks, toolCallId, toolName, output, isError
     clearProgressReporter(toolCallId);
     callbacks.onToolResult(toolCallId, output, isError);
 }
-/** Tools whose execution is driven by the AI SDK (they have an `execute` on
- *  the tool definition). By the time we see them in `processToolCalls`, the
- *  tool has already run and its result is already in `state.messages`. We
- *  can't pre-block these — only record for loop detection and annotate. */
-const AUTO_EXECUTED_TOOLS = new Set(['readFile', 'glob', 'grep', 'listDir', 'webFetch', 'webSearch', 'saveKnowledge']);
-/** Handle a single tool call. Returns when the call has been fully dispatched.
- *  `parentModel` is the LanguageModel instance for the current loop — needed
- *  by the task tool to pass as fallback when the sub-agent doesn't override. */
-async function handleToolCall(tc, state, options, callbacks, parentModel) {
-    const { toolName, input, toolCallId } = tc;
-    // ── askUser tool ──
-    // Skip the loop guard for askUser — the model asking the user the same
-    // clarifying question twice is almost always intentional (e.g. the user
-    // answered ambiguously) and blocking it would silently break the UX.
-    if (toolName === 'askUser') {
-        const question = input.question;
-        const optionsList = input.options;
-        const answer = await callbacks.onAskUser(question, optionsList);
-        pushToolResult(state, callbacks, toolCallId, toolName, `User answered: ${answer}`);
-        return;
-    }
-    // ── todoWrite tool ──
-    // Full-replacement semantics: every call rewrites state.todos with
-    // the model's payload. Auto-clears (drops to []) when every item is
-    // completed, mirroring Claude Code's TodoWriteTool behavior — the
-    // user's live UI panel goes back to "no checklist" once the work is
-    // done, instead of showing a stale all-✓ list forever.
-    if (toolName === 'todoWrite') {
-        const raw = input.todos ?? [];
-        const normalized = [];
-        for (const t of raw) {
-            const content = (t.content ?? '').trim();
-            const activeForm = (t.activeForm ?? '').trim();
-            // Need at least one identity field — otherwise this is just an
-            // empty entry and there's nothing useful to show or track.
-            if (!content && !activeForm)
-                continue;
-            normalized.push({
-                content: content || activeForm,
-                activeForm: activeForm || content,
-                status: t.status ?? 'pending',
-            });
-        }
-        const allDone = normalized.length > 0 && normalized.every((t) => t.status === 'completed');
-        state.todos = allDone ? [] : normalized;
-        callbacks.onTodosUpdate(state.todos);
-        const dropped = raw.length - normalized.length;
-        const droppedNote = dropped > 0
-            ? ` ${dropped} entr${dropped === 1 ? 'y was' : 'ies were'} dropped because they had neither content nor activeForm — please include both fields next time so the user sees clean labels.`
-            : '';
-        // Verification nudge: when completing a 3+ item list and none of
-        // them look like a verification step, remind the model to verify.
-        const VERIFY_RE = /\b(verif|test|check|lint|build|typecheck|tsc)\b/i;
-        const needsVerifyNudge = allDone &&
-            normalized.length >= 3 &&
-            !normalized.some((t) => VERIFY_RE.test(t.content) || VERIFY_RE.test(t.activeForm));
-        const verifyNote = needsVerifyNudge
-            ? ' Before wrapping up, verify your work — run tests, lint, or type-check as appropriate for this project.'
-            : '';
-        pushToolResult(state, callbacks, toolCallId, toolName, allDone
-            ? `All todos completed. Checklist cleared.${verifyNote}${droppedNote}`
-            : `Todo list updated. Keep the checklist current — mark items completed immediately when finished, and ensure exactly one item is in_progress.${droppedNote}`);
-        return;
-    }
-    // ── task tool (sub-agent dispatch) ──
-    if (toolName === 'task') {
-        const agentName = input.subagent_type;
-        const description = input.description;
-        const taskPrompt = input.prompt;
-        reportProgress(toolCallId, `Task: ${description} (${agentName})`);
-        const result = await runSubAgent({
-            parentState: state,
-            parentOptions: options,
-            callbacks,
-            toolCallId,
-            agentName,
-            description,
-            prompt: taskPrompt,
-            knowledgeContext: state.knowledgeContext ?? '',
-            isGitRepo: state.isGitRepo ?? false,
-        }, parentModel);
-        const statsLine = `<task_stats tool_calls="${result.toolCallCount}" tokens="${result.tokenUsage.totalTokens}" duration_ms="${result.durationMs}" />`;
-        pushToolResult(state, callbacks, toolCallId, toolName, `${result.resultText}\n${statsLine}`);
-        return;
-    }
-    // ── enterPlanMode tool ──
-    // Flip state.permissionMode → 'plan', invalidate the system-prompt
-    // cache so the next turn rebuilds it with the overlay, and reserve a
-    // plan-file path on state.currentPlanPath WITHOUT actually creating
-    // the file (the path is just a string until the model decides it
-    // wants a scratchpad). Plan mode is a conversation state, not a
-    // forced "write to a file" workflow — for Q&A and discussion the
-    // model never touches the file. The path is created lazily, the
-    // first time the model calls writeFile/edit on it (or when
-    // exitPlanMode persists the approved plan).
-    if (toolName === 'enterPlanMode') {
-        if (state.permissionMode === 'plan') {
-            pushToolResult(state, callbacks, toolCallId, toolName, 'Already in plan mode. Continue the conversation; call exitPlanMode when the user has asked for an implementation and you have a plan ready.');
-            return;
-        }
-        // Approval gate. Mirrors Claude Code: model can recommend plan
-        // mode but cannot enter on its own — user has to consent so the
-        // mode flip never feels like the model unilaterally hijacking the
-        // session. The same dialog component the write-tool path uses
-        // renders a "X-Code wants to enter plan mode" prompt with Yes/No.
-        const approved = await callbacks.onAskPermission({ toolCallId, toolName, input });
-        if (options.abortSignal?.aborted) {
-            pushToolResult(state, callbacks, toolCallId, toolName, '[Tool execution interrupted by user]', true);
-            return;
-        }
-        if (!approved) {
-            pushToolResult(state, callbacks, toolCallId, toolName, "User declined to enter plan mode. Continue with the user's request in default mode — make whatever edits or shell calls the task requires (subject to per-tool permission).", true);
-            return;
-        }
-        state.permissionMode = 'plan';
-        state.systemPromptCache = null;
-        // Derive the plan file path. Slug priority:
-        //   1. Model-supplied `topic` (3-5 English words specific to the
-        //      current task — most accurate when the user is mid-session
-        //      and the topic has shifted).
-        //   2. `state.taskSlug` (set once per session by agentLoop using
-        //      either local slugify or a one-shot LLM summary — already
-        //      handles CJK first messages).
-        //   3. Raw last-user-message text (final fallback; slugify will
-        //      reduce CJK to empty → timestamp-only filename).
-        if (!state.currentPlanPath) {
-            const topic = input.topic?.trim();
-            const fallbackText = lastUserMessageText(state.messages);
-            const explicitSlug = topic && topic.length > 0 ? topic : state.taskSlug || undefined;
-            state.currentPlanPath = makePlanFilePath(fallbackText, { slug: explicitSlug });
-        }
-        callbacks.onPlanModeChange('plan');
-        pushToolResult(state, callbacks, toolCallId, toolName, [
-            'Entered plan mode (user approved).',
-            '',
-            'Read-only tools are unrestricted (readFile, glob, grep, listDir, webSearch, webFetch).',
-            `Plan file path for this session: ${state.currentPlanPath}`,
-            'Use writeFile/edit on the plan file to build your plan; do NOT edit any other files',
-            'or run state-changing shell commands until the user approves your plan via exitPlanMode.',
-            '',
-            'Workflow: explore → update plan file → askUser → repeat.',
-            '',
-            'CRITICAL: when the plan is ready, call **exitPlanMode** to request approval — NOT',
-            'askUser. askUser cannot leave plan mode no matter how the user answers; only',
-            'exitPlanMode flips the mode and unblocks your writeFile/edit/shell calls.',
-        ].join('\n'));
-        return;
-    }
-    // ── exitPlanMode tool ──
-    // Triggers the user-approval gate. The plan body comes from
-    // `input.plan` (passed verbatim by the model). We persist it to the
-    // session's plan file as a permanent record before showing the
-    // approval dialog — that way even rejected plans leave a trace, and
-    // approved plans live alongside the implementation that follows.
-    // Approval flips state back to 'default' and invalidates the
-    // system-prompt cache so the next turn drops the plan-mode overlay.
-    // Rejection keeps the model in plan mode and tells it to revise.
-    if (toolName === 'exitPlanMode') {
-        if (state.permissionMode !== 'plan') {
-            pushToolResult(state, callbacks, toolCallId, toolName, 'Error: not in plan mode. exitPlanMode is only valid when the session is in plan mode.', true);
-            return;
-        }
-        // Source of truth for the plan body is the plan file the model has
-        // been writing to during planning (matches Claude Code: the model
-        // builds the plan incrementally via writeFile/edit, then calls
-        // exitPlanMode which reads the file). The optional `plan` override
-        // exists for rare cases where the model wants to substitute the
-        // file content with something different.
-        const planPath = state.currentPlanPath ??
-            makePlanFilePath(lastUserMessageText(state.messages), { slug: state.taskSlug || undefined });
-        state.currentPlanPath = planPath;
-        const planOverride = input.plan?.trim();
-        let planBody = planOverride ?? '';
-        if (!planBody) {
-            planBody = (await readPlan(planPath)).trim();
-        }
-        if (!planBody) {
-            pushToolResult(state, callbacks, toolCallId, toolName, `Error: the plan file at ${planPath} is empty. Write your plan to that file using writeFile or edit, then call exitPlanMode again.`, true);
-            return;
-        }
-        // If the model passed an override, persist it back to the plan
-        // file so the on-disk record matches what the user sees / approves.
-        let savedPath = planPath;
-        if (planOverride) {
-            try {
-                savedPath = await writePlan(planPath, planBody);
-                state.currentPlanPath = savedPath;
-            }
-            catch {
-                // Disk failure (read-only fs, permissions) is non-fatal — fall
-                // through to the approval dialog with the in-memory body.
-            }
-        }
-        const approved = await callbacks.onPlanApprovalRequest(planBody);
-        if (approved) {
-            // Default post-approval mode is `acceptEdits` — the user just
-            // vetted the plan, so making them click "Yes" on every writeFile
-            // / edit during implementation is pure friction. Shell commands
-            // still go through normal classification (always-allow for read-
-            // only, ask for mixed, deny for destructive) so we don't blanket-
-            // approve `rm -rf` on plan approval. Matches Claude Code's
-            // default "Yes, auto-accept edits" behavior.
-            state.permissionMode = 'acceptEdits';
-            state.systemPromptCache = null;
-            const persisted = savedPath ?? state.currentPlanPath;
-            state.currentPlanPath = null;
-            callbacks.onPlanModeChange('acceptEdits');
-            pushToolResult(state, callbacks, toolCallId, toolName, [
-                'Plan approved by user. Plan mode has been exited.',
-                persisted ? `The approved plan is saved at: ${persisted}` : '',
-                'You can now edit files and run shell commands. Start implementing the plan.',
-                '',
-                'For multi-step plans, call **todoWrite** first to break the plan into a',
-                'tracked checklist — the user sees a live panel of your progress and you',
-                'avoid losing track of remaining steps mid-implementation.',
-            ]
-                .filter(Boolean)
-                .join('\n'));
-            // Also inject a system-reminder-style user-role meta message so
-            // the model treats the mode flip as a fresh top-level instruction
-            // rather than just a tool result. Mirrors Claude Code's
-            // `## Exited Plan Mode` attachment (messages.ts:3847-3852) — gives
-            // the next turn a clear "the rules just changed" anchor.
-            state.messages.push({
-                role: 'user',
-                content: [
-                    '## Exited Plan Mode',
-                    '',
-                    'You have exited plan mode. You can now make edits, run tools, and take actions.',
-                    'Write tools (writeFile, edit) are now auto-approved (acceptEdits mode); shell commands',
-                    'still go through normal permission classification.',
-                    persisted ? `The plan file is located at ${persisted} if you need to reference it.` : '',
-                ]
-                    .filter(Boolean)
-                    .join('\n'),
-            });
-            return;
-        }
-        pushToolResult(state, callbacks, toolCallId, toolName, [
-            'Plan rejected by user. You are still in plan mode.',
-            "Read the user's next message for feedback, revise the plan accordingly,",
-            'and call exitPlanMode again with the revised body. Consider asking the user',
-            'a clarifying question via askUser if you are unsure what to change.',
-        ].join('\n'), true);
-        return;
-    }
-    // ── Doom-loop detection ──
-    // For manual tools we pre-block. For auto-executed tools the call has
-    // already run (result landed in state.messages via collectTurnResponse);
-    // we still record the hash and, on soft-block, push a supplemental notice
-    // so the next turn sees a clear stop signal. On hard-block, we additionally
-    // prompt the user before returning.
-    const isAutoExecuted = AUTO_EXECUTED_TOOLS.has(toolName);
+/** ── askUser ──
+ *  Bypasses the loop guard intentionally. The model asking the user the same
+ *  clarifying question twice is almost always deliberate (e.g. the user
+ *  answered ambiguously); blocking it would silently break the UX. */
+async function handleAskUser(ctx) {
+    const { input, toolCallId, toolName, state, callbacks } = ctx;
+    const question = input.question;
+    const optionsList = input.options;
+    const answer = await callbacks.onAskUser(question, optionsList);
+    pushToolResult(state, callbacks, toolCallId, toolName, `User answered: ${answer}`);
+}
+/** ── task (sub-agent dispatch) ── */
+async function handleTask(ctx) {
+    const { input, toolCallId, toolName, state, options, callbacks, parentModel } = ctx;
+    const agentName = input.subagent_type;
+    const description = input.description;
+    const taskPrompt = input.prompt;
+    reportProgress(toolCallId, `Task: ${description} (${agentName})`);
+    const result = await runSubAgent({
+        parentState: state,
+        parentOptions: options,
+        callbacks,
+        toolCallId,
+        agentName,
+        description,
+        prompt: taskPrompt,
+        knowledgeContext: state.knowledgeContext ?? '',
+        isGitRepo: state.isGitRepo ?? false,
+    }, parentModel);
+    const statsLine = `<task_stats tool_calls="${result.toolCallCount}" tokens="${result.tokenUsage.totalTokens}" duration_ms="${result.durationMs}" />`;
+    pushToolResult(state, callbacks, toolCallId, toolName, `${result.resultText}\n${statsLine}`);
+}
+/** Manual tools that bypass the loop guard and the writeFile/edit/shell
+ *  permission + execution pipeline below. Each handler owns its own
+ *  pushToolResult call. Adding a new bypass tool is a one-line entry here. */
+const BYPASS_LOOP_GUARD_HANDLERS = {
+    askUser: handleAskUser,
+    task: handleTask,
+    todoWrite: ({ input, toolCallId, state, callbacks }) => handleTodoWrite(input, toolCallId, state, callbacks, pushToolResult),
+    enterPlanMode: ({ input, toolCallId, state, options, callbacks }) => handleEnterPlanMode(input, toolCallId, state, options, callbacks, pushToolResult),
+    exitPlanMode: ({ input, toolCallId, state, callbacks }) => handleExitPlanMode(input, toolCallId, state, callbacks, pushToolResult),
+};
+/** Run the loop-guard machinery for a non-bypass tool. Returns true if the
+ *  tool was blocked (caller should stop dispatching).
+ *
+ *  Auto-executed tools never reach this path — `processToolCalls` skips
+ *  them earlier because their result is already in `state.messages` from
+ *  the SDK's `response.messages`, and re-running the loop-guard here would
+ *  push the synthesized result on top of that or inject a mid-iteration
+ *  user message that breaks the assistant→tool ordering strict providers
+ *  require.
+ *
+ *  `deferred` collects messages that must land AFTER the iteration's tool
+ *  results — pushing them mid-loop creates the
+ *  `assistant → tool A → user → tool B` pattern that DeepSeek 400s on. */
+async function applyLoopGuard(ctx, deferred) {
+    const { toolName, input, toolCallId, state, callbacks } = ctx;
     const loopCheck = checkForLoop(state, toolName, input, toolCallId);
-    if (loopCheck.kind !== 'ok') {
+    if (loopCheck.kind === 'ok') {
         recordToolCall(state, toolName, input, loopCheck.hash);
-        if (isAutoExecuted) {
-            // The tool result already exists in state.messages. Append a follow-up
-            // user-role notice so the model's next step has explicit context that
-            // this path is spinning — without this nudge, some models keep trying.
-            state.messages.push({
+        return false;
+    }
+    recordToolCall(state, toolName, input, loopCheck.hash);
+    const guardMessage = `[loop-guard] ${loopCheck.message}`;
+    // Manual tool — short-circuit by synthesising the result. The tool body
+    // never runs; no side effects, no permission prompt.
+    pushToolResult(state, callbacks, toolCallId, toolName, guardMessage, true);
+    if (loopCheck.kind === 'hard-block') {
+        const answer = await callbacks
+            .onAskUser(`The model keeps calling ${toolName} with identical arguments. How do you want to proceed?`, [
+            { label: 'Pause', description: 'Pause the turn — you can type a new instruction.' },
+            { label: 'Continue', description: 'Let the model keep trying; the loop guard stays armed.' },
+        ])
+            .catch(() => 'Pause');
+        if (answer.toLowerCase().startsWith('pause')) {
+            // Clear the recent-calls window so the guard doesn't immediately
+            // re-trigger on the next turn if the model legitimately retries
+            // once with the same args under the user's guidance.
+            state.recentToolCalls = [];
+            // Defer until after the iteration so the user-role message lands at
+            // the END of this turn's messages, not between tool results.
+            deferred.push({
                 role: 'user',
-                content: `[loop-guard] ${loopCheck.message}`,
+                content: '[loop-guard] User paused the loop. Wait for further instructions rather than calling more tools.',
             });
-            callbacks.onToolResult(toolCallId, `[loop-guard] ${loopCheck.message}`, true);
         }
-        else {
-            // Manual tool — short-circuit by synthesising the result. The tool body
-            // never runs; no side effects, no permission prompt.
-            pushToolResult(state, callbacks, toolCallId, toolName, `[loop-guard] ${loopCheck.message}`, true);
-        }
-        if (loopCheck.kind === 'hard-block') {
-            const answer = await callbacks
-                .onAskUser(`The model keeps calling ${toolName} with identical arguments. How do you want to proceed?`, [
-                { label: 'Pause', description: 'Pause the turn — you can type a new instruction.' },
-                { label: 'Continue', description: 'Let the model keep trying; the loop guard stays armed.' },
-            ])
-                .catch(() => 'Pause');
-            if (answer.toLowerCase().startsWith('pause')) {
-                // Clear the recent-calls window so the guard doesn't immediately
-                // re-trigger on the next turn if the model legitimately retries
-                // once with the same args under the user's guidance.
-                state.recentToolCalls = [];
-                state.messages.push({
-                    role: 'user',
-                    content: '[loop-guard] User paused the loop. Wait for further instructions rather than calling more tools.',
-                });
-            }
-        }
-        return;
     }
-    recordToolCall(state, toolName, input, loopCheck.hash);
-    // ── Permission check for write tools and shell ──
-    if (toolName === 'writeFile' || toolName === 'edit' || toolName === 'shell') {
-        const approved = await checkPermission({ toolCallId, toolName, input }, options.trustMode, callbacks.onAskPermission, state.permissionMode, process.cwd());
-        if (options.abortSignal?.aborted) {
-            pushToolResult(state, callbacks, toolCallId, toolName, '[Tool execution interrupted by user]', true);
-            return;
-        }
-        if (!approved) {
-            pushToolResult(state, callbacks, toolCallId, toolName, 'Permission denied by user.');
-            return;
-        }
+    return true;
+}
+/** Permission gate for writeFile/edit/shell. Returns true if execution
+ *  should continue, false if it was blocked / denied / aborted. */
+async function checkWriteOrShellPermission(ctx) {
+    const { toolName, input, toolCallId, state, options, callbacks } = ctx;
+    if (toolName !== 'writeFile' && toolName !== 'edit' && toolName !== 'shell')
+        return true;
+    const approved = await checkPermission({ toolCallId, toolName, input }, options.trustMode, callbacks.onAskPermission, state.permissionMode, process.cwd());
+    if (options.abortSignal?.aborted) {
+        pushToolResult(state, callbacks, toolCallId, toolName, '[Tool execution interrupted by user]', true);
+        return false;
     }
-    // ── Execute tool ──
-    let output;
-    let isError = false;
+    if (!approved) {
+        pushToolResult(state, callbacks, toolCallId, toolName, 'Permission denied by user.');
+        return false;
+    }
+    return true;
+}
+/** Run the underlying side-effecting tool body for writeFile/edit/shell.
+ *  Auto-executed tools return early because the AI SDK has already produced
+ *  their result. Returns the post-execution { output, isError } pair, or
+ *  null when there's nothing to push (auto-executed). */
+async function executeWriteOrShell(ctx) {
+    const { toolName, input, toolCallId, state, options, callbacks } = ctx;
     try {
         if (toolName === 'writeFile' || toolName === 'edit') {
-            output = await executeWriteTool(toolName, input, toolCallId, callbacks);
+            const output = await executeWriteTool(toolName, input, toolCallId, callbacks, options.abortSignal);
             // executeWriteTool returns "Error: ..." strings for in-band failures
             // (missing match, non-unique match) rather than throwing — surface
             // those as errored results so the scrollback line flips to red.
-            if (output.startsWith('Error:'))
-                isError = true;
-            else
+            const isError = isToolErrorString(output);
+            if (!isError)
                 state.filesModified.add(input.filePath);
+            return { output, isError };
         }
-        else if (toolName === 'shell') {
+        if (toolName === 'shell') {
             const timeout = input.timeout ?? 30000;
             const shellResult = await executeShell(input.command, timeout, options.abortSignal, callbacks, toolCallId);
-            output = shellResult.output;
-            isError = shellResult.isError;
-        }
-        else {
-            // Tools with execute (readFile, glob, grep, etc.) are auto-executed by AI SDK
-            return;
+            return { output: shellResult.output, isError: shellResult.isError };
         }
+        // Tools with execute (readFile, glob, grep, etc.) are auto-executed by AI SDK
+        return null;
     }
     catch (err) {
-        output = `Error: ${err instanceof Error ? err.message : String(err)}`;
-        isError = true;
+        return { output: toolErrorFromUnknown(err), isError: true };
+    }
+}
+/** Handle a single tool call. Returns when the call has been fully dispatched.
+ *  `parentModel` is the LanguageModel instance for the current loop — needed
+ *  by the task tool to pass as fallback when the sub-agent doesn't override.
+ *  `deferred` is the per-turn deferred-message queue threaded down to
+ *  `applyLoopGuard`; messages collected here are flushed after the entire
+ *  iteration in `processToolCalls`. */
+async function handleToolCall(tc, state, options, callbacks, parentModel, deferred) {
+    const ctx = {
+        toolName: tc.toolName,
+        input: tc.input,
+        toolCallId: tc.toolCallId,
+        state,
+        options,
+        callbacks,
+        parentModel,
+    };
+    const bypassHandler = BYPASS_LOOP_GUARD_HANDLERS[ctx.toolName];
+    if (bypassHandler) {
+        await bypassHandler(ctx);
+        return;
+    }
+    if (await applyLoopGuard(ctx, deferred))
+        return;
+    if (!(await checkWriteOrShellPermission(ctx)))
+        return;
+    const result = await executeWriteOrShell(ctx);
+    if (result == null)
+        return;
+    pushToolResult(state, callbacks, ctx.toolCallId, ctx.toolName, truncateToolResult(result.output), result.isError);
+}
+/** Collect every toolCallId the AI SDK actually committed to the
+ *  assistant message in this turn. The SDK's `result.toolCalls` promise
+ *  is independent of `response.messages` — when zod validation rejects
+ *  a malformed tool input mid-stream the SDK emits a `tool-error` chunk
+ *  and excludes that tool_call from response.messages, but it can still
+ *  surface in `toolCalls`. Running such a "ghost" call would have two
+ *  bad outcomes:
+ *    1. write/edit/shell would fire a real side effect for a call the
+ *       model never officially committed to.
+ *    2. The pushed tool_result would be an orphan in state.messages
+ *       (no preceding assistant tool_call with that id) and the next
+ *       API request would 400 with "tool must be a response to a
+ *       preceding message with tool_calls".
+ *  Returning the set lets `processToolCalls` filter the SDK's list
+ *  before any handler runs.
+ *
+ *  Walks from the END of state.messages backwards, collecting tool-call
+ *  ids from EVERY assistant message we encounter until we hit a
+ *  non-assistant/tool boundary — covers multi-assistant turn structures
+ *  some providers produce while still cutting off at the previous user
+ *  message so old turns' ids don't bleed in. */
+function collectActiveAssistantToolCallIds(state) {
+    const ids = new Set();
+    for (let i = state.messages.length - 1; i >= 0; i--) {
+        const msg = state.messages[i];
+        if (!msg)
+            continue;
+        if (msg.role === 'user')
+            break;
+        if (msg.role !== 'assistant')
+            continue;
+        if (!Array.isArray(msg.content))
+            continue;
+        for (const part of msg.content) {
+            if (part?.type === 'tool-call' && typeof part.toolCallId === 'string') {
+                ids.add(part.toolCallId);
+            }
+        }
+    }
+    return ids;
+}
+/** Collect tool_call_ids that ALREADY have a tool-result message in the
+ *  current turn's window of state.messages. Two distinct upstream paths
+ *  drop a result here before `processToolCalls` runs:
+ *    1. AI SDK auto-executed tools (readFile / glob / grep / listDir /
+ *       webFetch / webSearch) — their result is in `response.messages`
+ *       and gets pushed by `collectTurnResponse` before we iterate.
+ *    2. AI SDK auto-rejection of an unavailable tool — when a sub-agent's
+ *       toolFilter excludes a tool the model still emits a tool-call for
+ *       (e.g. `general-purpose` agent calling `writeFile`), the SDK
+ *       synthesizes an `error-text` tool-result so the assistant message
+ *       isn't left with an orphan tool-call.
+ *  In both cases re-running the tool here is wrong:
+ *    - For (1) the tool already executed; another run would duplicate
+ *      side effects (re-fetch a webpage, re-trigger a saveKnowledge).
+ *    - For (2) the tool isn't supposed to run at all in this agent's
+ *      filter, but `executeWriteTool` dispatches by name and would
+ *      happily fire writeFile, creating a real side effect AND pushing
+ *      a duplicate tool-result that DeepSeek 400s on next turn.
+ *  Same turn-boundary logic as collectActiveAssistantToolCallIds —
+ *  walk back from end-of-messages, stop at the first user message. */
+function collectFulfilledToolCallIds(state) {
+    const ids = new Set();
+    for (let i = state.messages.length - 1; i >= 0; i--) {
+        const msg = state.messages[i];
+        if (!msg)
+            continue;
+        if (msg.role === 'user')
+            break;
+        if (msg.role !== 'tool')
+            continue;
+        if (!Array.isArray(msg.content))
+            continue;
+        for (const part of msg.content) {
+            if (part?.type === 'tool-result' && typeof part.toolCallId === 'string') {
+                ids.add(part.toolCallId);
+            }
+        }
     }
-    pushToolResult(state, callbacks, toolCallId, toolName, truncateToolResult(output), isError);
+    return ids;
 }
-/** Handle all tool calls from a single model turn, sequentially.
- *  `parentModel` is threaded through so the task tool can pass it to runSubAgent. */
+/** Group consecutive `task` tool-calls into a single batch so they can be
+ *  dispatched in parallel; everything else gets a singleton batch and
+ *  dispatches one-at-a-time. Sub-agents launched by the `task` tool are
+ *  the only manual tool we hand-execute in `processToolCalls` that's
+ *  truly isolated:
+ *    - each `runSubAgent` builds a fresh `LoopState` (own messages, own
+ *      `recentToolCalls`, own todos, own permission mode)
+ *    - `parentState.tokenUsage` is updated by additive accumulation only
+ *      after the sub-agent completes, so concurrent updates can't get
+ *      torn (single-threaded event loop + plain `+=` writes)
+ *    - permission dialogs from concurrent sub-agents queue naturally on
+ *      the parent UI's `permissionResolversRef`
+ *  Every other manual tool mutates shared state and must stay serial:
+ *    - `writeFile` / `edit` mutate the filesystem and `state.filesModified`
+ *    - `shell` streams stdout/stderr to the parent UI as it arrives —
+ *      interleaved bytes from concurrent shells would scramble the live
+ *      indicator
+ *    - `askUser` / permission dialogs hold the UI; running two at once
+ *      would race the dialog state machine
+ *    - `todoWrite` / `enterPlanMode` / `exitPlanMode` mutate `LoopState`
+ *      fields that the next turn reads
+ *  Auto-executed tools (readFile / glob / grep / listDir / webFetch /
+ *  webSearch) don't appear here — by the time `processToolCalls` runs,
+ *  the SDK has already executed them and the skip-fulfilled pre-pass
+ *  short-circuits them out. */
+export function partitionToolCalls(calls) {
+    const batches = [];
+    let i = 0;
+    while (i < calls.length) {
+        let end = i + 1;
+        if (calls[i].toolName === 'task') {
+            while (end < calls.length && calls[end].toolName === 'task') {
+                end++;
+            }
+        }
+        batches.push(calls.slice(i, end));
+        i = end;
+    }
+    return batches;
+}
+/** Handle all tool calls from a single model turn.
+ *
+ *  Consecutive `task` tool-calls dispatch in parallel via Promise.all;
+ *  every other tool runs one at a time. See `partitionToolCalls` for the
+ *  full rationale on why only sub-agents are safe to fan out.
+ *
+ *  `parentModel` is threaded through so the task tool can pass it to
+ *  `runSubAgent`. */
 export async function processToolCalls(toolCalls, state, options, callbacks, parentModel) {
-    for (let i = 0; i < toolCalls.length; i++) {
-        const tc = toolCalls[i];
+    const activeIds = collectActiveAssistantToolCallIds(state);
+    const fulfilledIds = collectFulfilledToolCallIds(state);
+    // Per-turn queue for messages that must land AFTER every tool-result
+    // we push in this loop. Pushing a `role: 'user'` message between two
+    // tool-results creates the shape that DeepSeek's strict ordering
+    // rejects — we collect them here and flush at the end of the loop.
+    const deferred = [];
+    // Pre-pass: drop ghost calls and account for already-fulfilled calls.
+    // What survives goes into `liveCalls` which is what we actually
+    // dispatch. Doing this BEFORE partitioning keeps the parallel-batch
+    // dispatch simple — every entry in the batch is a real call we need
+    // to run.
+    const liveCalls = [];
+    for (const tc of toolCalls) {
+        // Skip ghost calls the SDK rejected mid-stream — see
+        // collectActiveAssistantToolCallIds for the full rationale. Don't
+        // pushToolResult either: the assistant message has no matching
+        // tool_call, so any result we emit would be an orphan that the
+        // sanitizer drops next turn anyway. Belt-and-suspenders: the
+        // sanitizer's reverse-orphan branch would still clean up if this
+        // check ever lets one through.
+        if (activeIds.size > 0 && !activeIds.has(tc.toolCallId)) {
+            debugLog('tool-exec.skip-ghost', `${tc.toolName} ${tc.toolCallId} — not in assistant tool_calls, likely SDK tool-error reject`);
+            continue;
+        }
+        // Skip already-fulfilled calls — see collectFulfilledToolCallIds.
+        // Still record the call in the loop-guard window so a runaway
+        // pattern on the same auto-executed tool can be circuit-broken on
+        // a future turn; if the guard fires, defer the user-role nudge
+        // until after iteration.
+        if (fulfilledIds.has(tc.toolCallId)) {
+            debugLog('tool-exec.skip-fulfilled', `${tc.toolName} ${tc.toolCallId} — tool-result already in state.messages`);
+            const loopCheck = checkForLoop(state, tc.toolName, tc.input, tc.toolCallId);
+            recordToolCall(state, tc.toolName, tc.input, loopCheck.hash);
+            if (loopCheck.kind !== 'ok') {
+                deferred.push({ role: 'user', content: `[loop-guard] ${loopCheck.message}` });
+            }
+            continue;
+        }
+        liveCalls.push(tc);
+    }
+    // Dispatch in batches. A batch of size 1 is functionally identical to
+    // a plain `await handleToolCall(...)` — Promise.all over a single
+    // promise resolves the same way — so the parallel path uniformly
+    // handles both cases.
+    const batches = partitionToolCalls(liveCalls);
+    let dispatched = 0;
+    for (const batch of batches) {
         // User pressed Esc / Ctrl+C. The currently running tool (if any) has
         // already been SIGKILL'd via the shell provider's cancelSignal. For
-        // every remaining tool_call from this turn we still need to push a
-        // synthetic tool_result — orphan tool_calls without a matching result
-        // would make the next API request fail with "tool_use without
-        // tool_result" the moment the user types another prompt.
+        // every remaining tool_call we still need to push a synthetic
+        // tool_result — orphan tool_calls without a matching result would
+        // make the next API request fail with "tool_use without tool_result"
+        // the moment the user types another prompt.
         if (options.abortSignal?.aborted) {
-            for (let j = i; j < toolCalls.length; j++) {
-                const skipped = toolCalls[j];
-                pushToolResult(state, callbacks, skipped.toolCallId, skipped.toolName, '[Tool execution interrupted by user]', true);
+            for (let j = dispatched; j < liveCalls.length; j++) {
+                pushToolResult(state, callbacks, liveCalls[j].toolCallId, liveCalls[j].toolName, '[Tool execution interrupted by user]', true);
             }
-            return;
+            break;
         }
-        await handleToolCall(tc, state, options, callbacks, parentModel);
+        await Promise.all(batch.map((tc) => handleToolCall(tc, state, options, callbacks, parentModel, deferred)));
+        dispatched += batch.length;
     }
+    // Flush deferred messages AFTER all tool_results in this turn — they
+    // sit at the very end of state.messages, where the next runTurn sees
+    // them as the most recent context but they don't break the
+    // assistant→tool ordering the SDK will replay to the provider.
+    if (deferred.length > 0)
+        state.messages.push(...deferred);
 }
 //# sourceMappingURL=tool-execution.js.map