@bubblebrain-ai/bubble 0.0.5 → 0.0.6

package/dist/agent/task-size.d.ts

@@ -0,0 +1,9 @@
+import type { ContentPart } from "../types.js";
+/**
+ * Coarse "is this a small / focused task" classifier. Used to inject a hint
+ * that suppresses the default exploration-first protocol when the user's
+ * request is clearly a one-shot create or single-file tweak. Counterpart to
+ * `task-classifier.ts` which categorizes by *kind*, not *size*.
+ */
+export type TaskSize = "small" | "normal";
+export declare function classifyTaskSize(input: string | ContentPart[]): TaskSize;

package/dist/agent/task-size.js

@@ -0,0 +1,33 @@
+// Two-part match: a "create" verb AND a "deliverable" noun in the same
+// sentence is a strong signal of a focused, one-shot task.
+const SMALL_TASK_VERBS = [
+    /\b(write|create|generate|make|draft|build|add)\b/i,
+    /帮我写|帮我创建|帮我生成|写(个|一个|一份)|新建一个|做(个|一个|一份)|生成(个|一个|一份)|搞(个|一个|一份)/i,
+];
+const SMALL_TASK_NOUNS = [
+    /\b(file|page|component|script|snippet|function|class|test|html|css|js|ts|tsx|jsx|md|markdown|hello world)\b/i,
+    /(文件|页面|组件|脚本|片段|函数|类|测试|html|css|介绍|文章|页|说明|示例|demo)/i,
+];
+function matchesSmallTaskPattern(text) {
+    return SMALL_TASK_VERBS.some((re) => re.test(text))
+        && SMALL_TASK_NOUNS.some((re) => re.test(text));
+}
+const LARGE_TASK_NEGATIONS = [
+    /\b(refactor|rewrite|migrate|overhaul|integrate|architect|review the codebase|whole project|across the codebase)\b/i,
+    /多个|批量|全部|所有|整个项目|整个仓库|架构|重构|端到端|跨模块/i,
+];
+export function classifyTaskSize(input) {
+    const text = (typeof input === "string"
+        ? input
+        : input
+            .filter((part) => part.type === "text")
+            .map((part) => part.text)
+            .join("\n")).trim();
+    if (!text)
+        return "normal";
+    // Up to ~120 chars with a small-task verb+noun match and no negation: small.
+    if (text.length <= 120 && matchesSmallTaskPattern(text)) {
+        return LARGE_TASK_NEGATIONS.some((re) => re.test(text)) ? "normal" : "small";
+    }
+    return "normal";
+}

package/dist/agent/tool-intent.d.ts

@@ -32,3 +32,4 @@ export interface ParsedReadCommand {
 }
 export declare function parseSearchBashCommand(command: string): ParsedSearchCommand | undefined;
 export declare function parseReadBashCommand(command: string): ParsedReadCommand | undefined;
+export declare function shellSplit(command: string): string[];

package/dist/agent/tool-intent.js

@@ -256,7 +256,7 @@ function parseLineCount(value) {
     const parsed = Number(value.replace(/^\+/, ""));
     return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
 }
-function shellSplit(command) {
+export function shellSplit(command) {
     const tokens = [];
     let current = "";
     let quote = null;

package/dist/agent.js

@@ -338,6 +338,9 @@ export class Agent {
                                 if (chunk.argumentsFull !== undefined) {
                                     currentToolCall.args = chunk.argumentsFull;
                                 }
+                                if (chunk.argumentsCorrupt) {
+                                    currentToolCall.argsCorrupt = true;
+                                }
                                 if (chunk.arguments) {
                                     yield {
                                         type: "tool_call_delta",
@@ -353,6 +356,7 @@ export class Agent {
                                     id: currentToolCall.id,
                                     name: currentToolCall.name,
                                     arguments: currentToolCall.args,
+                                    ...(currentToolCall.argsCorrupt ? { argsCorrupt: true } : {}),
                                 });
                                 yield {
                                     type: "tool_call_end",
@@ -405,10 +409,14 @@ export class Agent {
                 for (let index = 0; index < assistantMsg.toolCalls.length; index++) {
                     const tc = assistantMsg.toolCalls[index];
                     try {
-                        parsedCalls.push({ ...tc, parsedArgs: JSON.parse(tc.arguments) });
+                        parsedCalls.push({
+                            ...tc,
+                            parsedArgs: JSON.parse(tc.arguments),
+                            ...(tc.argsCorrupt ? { argsCorrupt: true } : {}),
+                        });
                     }
                     catch {
-                        parsedCalls.push({ ...tc, parsedArgs: {} });
+                        parsedCalls.push({ ...tc, parsedArgs: {}, argsCorrupt: true });
                     }
                 }
                 const executedResults = [];
@@ -1084,6 +1092,25 @@ export class Agent {
                 isError: true,
             };
         }
+        if (toolCall.argsCorrupt) {
+            return {
+                content: `Error: The arguments for "${toolCall.name}" failed to parse as JSON, indicating the tool call was truncated or malformed mid-stream. ` +
+                    `Re-issue the call with valid JSON arguments; do not assume the previous attempt ran.`,
+                isError: true,
+                status: "blocked",
+                metadata: { kind: "security", reason: "args_corrupt" },
+            };
+        }
+        const missingRequired = findMissingRequiredArgs(tool.parameters, toolCall.parsedArgs);
+        if (missingRequired.length > 0) {
+            return {
+                content: `Error: Tool "${toolCall.name}" was called without required argument${missingRequired.length === 1 ? "" : "s"}: ${missingRequired.map((name) => `"${name}"`).join(", ")}. ` +
+                    `Re-issue the call with all required fields filled. Do not assume the previous attempt ran with default values.`,
+                isError: true,
+                status: "blocked",
+                metadata: { kind: "security", reason: "missing_required_args", missing: missingRequired },
+            };
+        }
         try {
             return await tool.execute(toolCall.parsedArgs, {
                 cwd,
@@ -1102,6 +1129,23 @@ export class Agent {
         }
     }
 }
+function findMissingRequiredArgs(schema, args) {
+    const required = schema?.required;
+    if (!required || required.length === 0)
+        return [];
+    const missing = [];
+    for (const name of required) {
+        const value = args ? args[name] : undefined;
+        // Empty strings/arrays are intentionally allowed — writing an empty file
+        // or passing an empty list can be legitimate. Only undefined/null counts
+        // as "missing", because the observed failure mode is `finalArgs: "{}"`
+        // where the field is entirely absent.
+        if (value === undefined || value === null) {
+            missing.push(name);
+        }
+    }
+    return missing;
+}
 function estimateResidentChars(messages) {
     let total = 0;
     for (const message of messages) {

package/dist/orchestrator/default-hooks.js

@@ -1,8 +1,9 @@
 import { classifyTask } from "../agent/task-classifier.js";
+import { classifyTaskSize } from "../agent/task-size.js";
 import { EvidenceTracker } from "../agent/evidence-tracker.js";
 import { ExecutionGovernor } from "../agent/execution-governor.js";
 import { arbitrateToolCall } from "../agent/tool-arbiter.js";
-import { buildFinalizeOpportunityReminder, buildTaskSummaryReminder, buildVerificationFailureReminder, buildVerificationReminder, buildWorkflowPhaseReminder, } from "../prompt/reminders.js";
+import { buildEditRetryEscalationReminder, buildRedundantReadReminder, buildSmallTaskHint, buildTaskSummaryReminder, buildWorkflowPhaseReminder, } from "../prompt/reminders.js";
 import { reminderForTaskType } from "../prompt/task-reminders.js";
 import { formatCoverageSummary, resolveWorkflowPhase } from "./workflow.js";
 export function createDefaultHooks() {
@@ -16,6 +17,13 @@ export function createDefaultHooks() {
                 if (taskReminder) {
                     ctx.queueReminder(taskReminder);
                 }
+                // Small-task hint: counterweight to the default protocol's exploration
+                // bias, only fires once per run on focused one-shot requests like
+                // "写个 HTML 介绍元旦". Don't issue for the same input twice.
+                if (!ctx.state.smallTaskHintSent && classifyTaskSize(ctx.input) === "small") {
+                    ctx.state.smallTaskHintSent = true;
+                    ctx.queueReminder(buildSmallTaskHint());
+                }
                 if (taskType === "security_investigation") {
                     ctx.state.evidenceTracker = new EvidenceTracker();
                     ctx.state.workflowPhase = "investigate";
@@ -75,21 +83,58 @@ export function createDefaultHooks() {
                 }
                 ctx.state.evidenceTracker?.observe(ctx.toolCall, ctx.result);
                 ctx.state.governor?.afterToolResult(ctx.toolCall, ctx.result);
-                if (isCodeWriteResult(ctx.toolCall, ctx.result)) {
-                    markCodeChanged(ctx.state);
-                }
-                else if (ctx.state.codeChanged && isVerificationAttempt(ctx.toolCall, ctx.result)) {
-                    ctx.state.verificationAttempted = true;
-                    if (isSuccessfulToolResult(ctx.result)) {
-                        ctx.state.verificationCompleted = true;
-                        ctx.state.verificationFailed = false;
+                // Edit/write retry-escalation: if the same tool with the same args
+                // failed twice in a row, models — especially thinking-heavy ones —
+                // can spiral on "identical content" / "not found" errors. Nudge them
+                // to change strategy.
+                if ((ctx.toolCall.name === "edit" || ctx.toolCall.name === "write") && ctx.result.isError) {
+                    const hash = hashEditCall(ctx.toolCall);
+                    const history = ctx.state.recentEditFailures ?? (ctx.state.recentEditFailures = []);
+                    history.push(hash);
+                    // Keep last 4 entries.
+                    if (history.length > 4)
+                        history.shift();
+                    const len = history.length;
+                    if (len >= 2 && history[len - 1] === history[len - 2] && !ctx.state.editRetryReminderSent) {
+                        ctx.state.editRetryReminderSent = true;
+                        const summary = ctx.result.content.split("\n")[0] || "";
+                        ctx.queueReminder(buildEditRetryEscalationReminder(`Last failure: ${ctx.toolCall.name} on the same target with identical arguments. ${summary}`));
                     }
-                    else {
-                        ctx.state.verificationCompleted = false;
-                        ctx.state.verificationFailed = true;
-                        ctx.state.finalizeReminderQueued = false;
+                }
+                else if ((ctx.toolCall.name === "edit" || ctx.toolCall.name === "write") && !ctx.result.isError) {
+                    // Successful mutation resets the dedup state so a later, unrelated
+                    // failure won't fire the reminder spuriously.
+                    ctx.state.recentEditFailures = [];
+                    ctx.state.editRetryReminderSent = false;
+                }
+                // Redundant-Read detection: same file path read twice within this turn.
+                // Soft single-shot reminder, governor handles cumulative read budgets.
+                if (ctx.toolCall.name === "read" && !ctx.result.isError) {
+                    const rawPath = ctx.toolCall.parsedArgs?.path ?? ctx.toolCall.parsedArgs?.file_path;
+                    const path = typeof rawPath === "string" ? rawPath : undefined;
+                    if (path) {
+                        const seen = ctx.state.recentReadPaths ?? (ctx.state.recentReadPaths = []);
+                        const flagged = ctx.state.redundantReadReminded ?? (ctx.state.redundantReadReminded = new Set());
+                        if (seen.includes(path) && !flagged.has(path)) {
+                            flagged.add(path);
+                            ctx.queueReminder(buildRedundantReadReminder(path));
+                        }
+                        seen.push(path);
+                        if (seen.length > 16)
+                            seen.shift();
                     }
                 }
+                if (isCodeWriteResult(ctx.toolCall, ctx.result)) {
+                    markCodeChanged(ctx.state);
+                }
+                // Removed: active verification tracking. The previous design nagged the
+                // model every turn until it ran a recognised verification command, and
+                // narrowly accepted only test/lint commands — which meant ad-hoc python
+                // checks did not count, the nag never cleared, and reasoning models
+                // (DeepSeek v4-pro with hex-blindness) spiraled trying to "prove" the
+                // edit was correct. CC's approach is the opposite: verify when there
+                // is something real to verify, say so explicitly when there isn't, and
+                // trust the model to judge. We follow that.
                 if (ctx.toolCall.name === "task") {
                     ctx.queueReminder(buildTaskSummaryReminder());
                 }
@@ -110,46 +155,17 @@ export function createDefaultHooks() {
                 if (ctx.state.governor?.snapshot().searchFrozen && allSearchResultsWereLowSignal) {
                     ctx.requestTextOnlyTurn("Search continuation has become low-yield. Summarize the strongest evidence already collected instead of continuing broad exploration.");
                 }
-                const changedThisTurn = ctx.toolResults.some((result) => result.metadata?.kind === "write" || result.metadata?.kind === "edit");
-                if (changedThisTurn && !ctx.state.verificationAttempted && !ctx.state.verificationCompleted && !ctx.state.verificationReminderQueued) {
-                    ctx.state.verificationReminderQueued = true;
-                    ctx.queueReminder(buildVerificationReminder("The previous turn changed files and no verification evidence has been observed yet."));
-                }
-                if (ctx.state.codeChanged && ctx.state.verificationFailed && !ctx.state.verificationFailureReminderQueued) {
-                    ctx.state.verificationFailureReminderQueued = true;
-                    ctx.queueReminder(buildVerificationFailureReminder("A verification command or runtime check was attempted after file changes, but it did not pass."));
-                }
-                if (ctx.state.codeChanged && ctx.state.verificationCompleted && !ctx.state.finalizeReminderQueued) {
-                    ctx.state.finalizeReminderQueued = true;
-                    ctx.queueReminder(buildFinalizeOpportunityReminder("A relevant verification command or runtime check passed after file changes."));
-                }
+                // Verification reminders intentionally removed. See afterToolCall.
             },
-            afterTurn(ctx) {
-                if (ctx.state.codeChanged && ctx.state.verificationFailed && !ctx.state.verificationFailureReminderSent) {
-                    ctx.state.verificationFailureReminderSent = true;
-                    ctx.state.forceContinuationReason = "Files were changed, but the latest verification evidence failed.";
-                    ctx.queueReminder(buildVerificationFailureReminder(ctx.state.forceContinuationReason));
-                    return;
-                }
-                if (ctx.state.codeChanged && !ctx.state.verificationAttempted && !ctx.state.verificationCompleted && !ctx.state.finalVerificationReminderSent) {
-                    ctx.state.finalVerificationReminderSent = true;
-                    ctx.state.forceContinuationReason = "Files were changed but no verification evidence was observed before the final answer.";
-                    ctx.queueReminder(buildVerificationReminder(ctx.state.forceContinuationReason));
-                }
+            afterTurn() {
+                // Verification force-continuation removed. The model decides whether
+                // verification is meaningful for the task, per the system prompt.
             },
         },
     ];
 }
 function markCodeChanged(state) {
     state.codeChanged = true;
-    state.verificationAttempted = false;
-    state.verificationCompleted = false;
-    state.verificationFailed = false;
-    state.verificationReminderQueued = false;
-    state.finalVerificationReminderSent = false;
-    state.verificationFailureReminderQueued = false;
-    state.verificationFailureReminderSent = false;
-    state.finalizeReminderQueued = false;
 }
 function isCodeWriteResult(_toolCall, result) {
     if (result.isError || result.status === "blocked" || result.status === "command_error") {
@@ -157,31 +173,26 @@ function isCodeWriteResult(_toolCall, result) {
     }
     return result.metadata?.kind === "write" || result.metadata?.kind === "edit";
 }
-function isSuccessfulToolResult(result) {
-    if (result.isError) {
-        return false;
+function hashEditCall(toolCall) {
+    // Cheap fingerprint that identifies "same edit/write call". JSON of the
+    // sorted parsed args is good enough — we only need stable equality between
+    // identical calls, not cryptographic strength.
+    try {
+        return `${toolCall.name}:${stableStringify(toolCall.parsedArgs)}`;
+    }
+    catch {
+        return `${toolCall.name}:${toolCall.arguments}`;
     }
-    return result.status !== "blocked" && result.status !== "command_error" && result.status !== "timeout";
 }
-function isVerificationAttempt(toolCall, result) {
-    if (toolCall.name === "lsp") {
-        return true;
+function stableStringify(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(stableStringify).join(",")}]`;
     }
-    if (toolCall.name !== "bash") {
-        return false;
+    if (value && typeof value === "object") {
+        const entries = Object.keys(value)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`);
+        return `{${entries.join(",")}}`;
     }
-    const command = typeof result.metadata?.command === "string"
-        ? result.metadata.command
-        : typeof toolCall.parsedArgs.command === "string"
-            ? toolCall.parsedArgs.command
-            : "";
-    return isVerificationCommand(command);
-}
-function isVerificationCommand(command) {
-    const normalized = command.trim().toLowerCase();
-    return /\b(npm|pnpm|yarn|bun)\s+(test|run\s+(test|build|typecheck|lint|check|tsc)|exec\s+tsc)\b/.test(normalized)
-        || /\b(npx|pnpm\s+exec|bunx)\s+(vitest|tsc|eslint|playwright)\b/.test(normalized)
-        || /\b(python3?|uv\s+run\s+python3?|poetry\s+run\s+python3?)\s+(-m\s+)?(pytest|unittest|ruff|mypy)\b/.test(normalized)
-        || /\b(make|cmake)\s+(test|check)\b/.test(normalized)
-        || /\b(vitest|tsc|pytest|ruff|mypy|ctest|cargo\s+test|go\s+test|swift\s+test|mvn\s+test|gradle\s+test|\.\/gradlew\s+test)\b/.test(normalized);
+    return JSON.stringify(value ?? null);
 }

package/dist/orchestrator/hooks.d.ts

@@ -14,14 +14,11 @@ export interface TurnHookState {
     forceTextOnlyReason?: string;
     forceContinuationReason?: string;
     codeChanged?: boolean;
-    verificationAttempted?: boolean;
-    verificationCompleted?: boolean;
-    verificationFailed?: boolean;
-    verificationReminderQueued?: boolean;
-    finalVerificationReminderSent?: boolean;
-    verificationFailureReminderQueued?: boolean;
-    verificationFailureReminderSent?: boolean;
-    finalizeReminderQueued?: boolean;
+    smallTaskHintSent?: boolean;
+    recentEditFailures?: string[];
+    editRetryReminderSent?: boolean;
+    recentReadPaths?: string[];
+    redundantReadReminded?: Set<string>;
     taskBudget?: {
         total: number;
         spent: number;

package/dist/prompt/compose.js

@@ -79,6 +79,9 @@ function buildGuidelines(tools, extraGuidelines) {
     if (tools.includes("question")) {
         add("When the user is explicitly discussing, brainstorming, or shaping an approach instead of asking for immediate execution, use the question tool for targeted clarification or preference choices when it would materially improve the discussion; do not use it for generic permission-to-proceed questions");
     }
+    if (tools.includes("todo_write")) {
+        add("Use todo_write to plan any task that needs three or more concrete steps before you start. Mark each item completed as soon as it is done; do not batch updates");
+    }
     for (const item of extraGuidelines) {
         add(item);
     }

package/dist/prompt/environment.js

@@ -15,6 +15,7 @@ export const defaultToolSnippets = {
     close_agent: "Close or cancel a spawned subagent thread",
     question: "Ask the user structured questions when clarification or preference choices would materially improve the work",
     skill: "Load a named skill with specialized instructions and bundled resources",
+    todo_write: "Plan and track multi-step work. Mark each task completed as soon as it is done — do not batch.",
 };
 export const defaultToolNames = [
     "read",
@@ -32,6 +33,7 @@ export const defaultToolNames = [
     "close_agent",
     "question",
     "skill",
+    "todo_write",
 ];
 export function buildEnvironmentPrompt(options = {}) {
     const configuredProvider = options.configuredProvider ?? "unknown";

package/dist/prompt/provider-prompts/deepseek.js

@@ -3,6 +3,5 @@ export function buildDeepSeekProviderPrompt(agentName) {
 
 Prefer short plans followed by concrete tool use. Avoid broad speculation.
 After each tool result, update your understanding before choosing the next action.
-Do not repeat equivalent searches unless the previous result changed the search space.
-When provider/API behavior is involved, inspect serialization and request-shape code before changing generic agent logic.`;
+Do not repeat equivalent searches unless the previous result changed the search space.`;
 }

package/dist/prompt/provider-prompts/kimi.js

@@ -2,6 +2,5 @@ export function buildKimiProviderPrompt(agentName) {
     return `You are ${agentName}, a terminal coding agent running on a Kimi/Moonshot model.
 
 Keep tool use disciplined: pursue one concrete hypothesis at a time, read results carefully, and converge after evidence is sufficient.
-Do not fan out into many parallel search directions unless the task truly requires it.
-For tool-call or reasoning-mode issues, inspect message history serialization before changing unrelated agent behavior.`;
+Do not fan out into many parallel search directions unless the task truly requires it.`;
 }

package/dist/prompt/reminders.d.ts

@@ -30,6 +30,23 @@ export declare function buildWorkflowPhaseReminder(input: {
     pending: string[];
 }): string;
 export declare function buildTaskSummaryReminder(): string;
-export declare function buildVerificationReminder(reason: string): string;
-export declare function buildVerificationFailureReminder(reason: string): string;
-export declare function buildFinalizeOpportunityReminder(reason: string): string;
+/**
+ * Fired when the same edit/write tool call (identical tool name + args) has
+ * just failed for the second time in a row. Models — especially thinking-heavy
+ * ones — can otherwise spiral on `No changes made: identical content` or
+ * `oldText not found` because their internal reasoning convinces them they
+ * are typing the change correctly even though the JSON args arrive identical.
+ * This nudge forces a strategy change.
+ */
+export declare function buildEditRetryEscalationReminder(reason: string): string;
+/**
+ * Fired the FIRST time the model re-reads a file it already read in this turn.
+ * Soft — does not freeze the tool. Just prevents a 3rd / 4th re-read.
+ */
+export declare function buildRedundantReadReminder(path: string): string;
+/**
+ * Injected once at task start when the user's input looks like a small,
+ * focused task (e.g. "write an HTML page about X"). Counterweight to the
+ * default protocol which biases toward thorough exploration.
+ */
+export declare function buildSmallTaskHint(): string;

package/dist/prompt/reminders.js

@@ -171,33 +171,59 @@ Treat the task output as a bounded subtask result:
 - do not re-run the same exploratory search unless the subtask uncovered a concrete contradiction
 `);
 }
-export function buildVerificationReminder(reason) {
+// Removed: buildVerificationReminder / buildVerificationFailureReminder.
+// The verification reminder ladder pressured the model to run a "verification"
+// after every file change. For models with hex-tokenization blind spots (e.g.
+// DeepSeek v4-pro), this triggered death loops where the model wrote ad-hoc
+// validation scripts that found the bug but could never fix it. CC trusts the
+// model to decide when verification is meaningful; we follow that.
+/**
+ * Fired when the same edit/write tool call (identical tool name + args) has
+ * just failed for the second time in a row. Models — especially thinking-heavy
+ * ones — can otherwise spiral on `No changes made: identical content` or
+ * `oldText not found` because their internal reasoning convinces them they
+ * are typing the change correctly even though the JSON args arrive identical.
+ * This nudge forces a strategy change.
+ */
+export function buildEditRetryEscalationReminder(reason) {
     return wrapInSystemReminder(`
-Verification required before final answer.
+The same edit/write call has failed twice with identical arguments.
 
 ${reason}
 
-You have changed files in this turn. Run the narrowest meaningful verification command or runtime check before finalizing.
-If verification truly cannot be run, state the concrete blocker and the residual risk.
+Stop retrying the same call. Pick one of:
+- Re-read the target file and compare the actual bytes to your intended oldText / newText. Trailing whitespace, unicode lookalikes, or off-by-one boundaries are common causes.
+- If you intended to add a single character (e.g. fixing a 5-digit hex color to 6 digits), confirm that your newText string actually contains the added character before sending again.
+- Use the write tool with overwrite=true and the full new content instead of edit — useful when the change spans many lines or the diff anchor is ambiguous. Existing files must be read or modified in this session before full-file replacement.
+- If you cannot determine the cause, ask the user for clarification.
 `);
 }
-export function buildVerificationFailureReminder(reason) {
+/**
+ * Fired the FIRST time the model re-reads a file it already read in this turn.
+ * Soft — does not freeze the tool. Just prevents a 3rd / 4th re-read.
+ */
+export function buildRedundantReadReminder(path) {
     return wrapInSystemReminder(`
-Verification failed after file changes.
-
-${reason}
-
-Do not finalize as complete while this failure is unresolved. Make one focused fix and rerun the most relevant verification.
-If you cannot fix it, explain the concrete blocker and the residual risk instead of claiming success.
+You already read ${path} earlier in this turn. Use the content already in context rather than re-reading.
+Only re-read this path if a subsequent tool call (edit/write/bash) modified it since.
 `);
 }
-export function buildFinalizeOpportunityReminder(reason) {
+/**
+ * Injected once at task start when the user's input looks like a small,
+ * focused task (e.g. "write an HTML page about X"). Counterweight to the
+ * default protocol which biases toward thorough exploration.
+ */
+export function buildSmallTaskHint() {
     return wrapInSystemReminder(`
-Completion checkpoint.
-
-${reason}
+This appears to be a small, focused task (short request, single deliverable, no integration ambiguity).
 
-If this satisfies the user's request, provide the final answer now.
-Continue using tools only if there is a concrete remaining requirement, failing check, or missing deliverable.
+Prefer direct execution over exploration:
+- If the target file path is given or obvious, use write/edit directly.
+- Do not glob, read, or grep adjacent files unless the request explicitly references them.
+- Do not pre-plan with todo_write for tasks that can be done in one or two tool calls.
+- Skip the "investigate the codebase" step that applies to larger changes.
 `);
 }
+// Removed: buildFinalizeOpportunityReminder. Was paired with the verification
+// nag ladder. Without the ladder, "you can finalize now" advice is redundant —
+// the model finalises whenever its own judgement says the task is done.

package/dist/prompt/runtime.js

@@ -1,30 +1,24 @@
+// Compact, prose-shaped guidelines. Each line is one rule. The set is kept
+// short on purpose: a thinking-heavy model burns reasoning tokens on every
+// rule it has to weigh per turn, and most behaviors should be background
+// disposition, not active checklist items. Add to this list only when an
+// observed failure cannot be addressed by an existing rule.
 const defaultGuidelines = [
-    "Inspect relevant files, command output, or runtime state before making claims about code behavior",
-    "Separate confirmed facts from inference when the evidence is incomplete",
-    "Prefer runtime and call-chain evidence over README text or configuration names for behavior questions",
-    "Before editing or writing files, read them first if they exist",
-    "Use edit for targeted changes to existing files; use write for creating new files",
-    "Edit only the files required for the requested change",
-    "Prefer structured search tools over bash for repository searches whenever possible",
-    "Do not repeat near-identical searches when they are not producing new evidence",
-    "When investigating configuration or security questions, stop once the relevant load path, storage path, and exposure path are identified",
-    "Use spawn_agent and wait_agent for bounded investigative subproblems instead of letting the main loop churn on repeated exploratory searches",
-    "After code edits, run the narrowest meaningful verification command or explain why verification is not possible",
-    "When finishing a coding task, report what changed, where it changed, verification results, and remaining risk",
-    "Be concise in your responses",
+    "Ground decisions in the codebase: inspect relevant files, command output, or runtime state before making claims about behavior. Separate confirmed facts from inference when evidence is incomplete.",
+    "Choose the smallest coherent change. Edit only the files required for the requested change; do not refactor or improve adjacent code unprompted.",
+    "For modifications to existing code, read the file first. For brand-new files whose target path is known and does not exist, write directly without exploratory reading. Use edit for small targeted changes; use write with overwrite=true for intentional full-file replacement of an existing file. Never delete and recreate a file just to overwrite it.",
+    "Prefer structured tools (glob, grep, lsp, read) over bash for search and inspection. Do not repeat a near-identical search or re-read the same file unless new evidence changes the question.",
+    "If a tool fails, diagnose the error before switching tactics. Do not retry the identical call with identical arguments. After two equivalent failures, switch approach — re-read the file, use a different tool, rewrite the whole file with write overwrite=true, or ask the user.",
+    "Before reporting a task complete, verify it works when verification is meaningful and cheap — run the existing test, execute the script, check the output. If no test exists, the change is purely declarative (static HTML/markdown/config), or running the code is not practical, state that explicitly rather than inventing a verification step. Do not write throwaway validation scripts to prove correctness; if there is no real check to run, report the change and stop.",
 ];
 export function buildRuntimePrompt(options = {}) {
-    const thinkingLevel = options.thinkingLevel ?? "off";
     const guidelines = dedupe(defaultGuidelines, options.guidelines ?? []);
-    return `Current thinking level: ${thinkingLevel}
-
-Execution protocol:
-1. Understand the user's requested outcome and current constraints.
-2. Inspect the relevant files or state before making claims or edits.
-3. Choose the smallest coherent change that solves the actual problem.
-4. Edit only the necessary files.
-5. Verify with the narrowest meaningful command or runtime check when possible.
-6. Finish with changed files, verification results, and unresolved risk.
+    // The execution flow is stated as a single prose sentence rather than a
+    // numbered protocol. Numbered checklists prompt thinking models to walk
+    // each step explicitly in their reasoning every turn, even for trivial
+    // tasks — multiplying latency without improving quality. Prose lets the
+    // protocol act as background disposition.
+    return `Work by understanding the requested outcome, grounding decisions in the codebase, making the smallest coherent change, and verifying when possible. Scale your effort to the task: a one-file create-or-edit deserves direct execution, not extensive pre-exploration.
 
 Guidelines:
 ${guidelines.map((item) => `- ${item}`).join("\n")}`;

package/dist/provider.d.ts

@@ -5,6 +5,10 @@
  */
 import type { Provider, ProviderMessage, StreamChunk, ThinkingLevel } from "./types.js";
 type ReasoningContentEcho = "tool_calls" | "all";
+export type ToolArgsMergeMode = "delta" | "snapshot";
+export interface TranslateOpenAIStreamOptions {
+    toolArgsMergeMode?: ToolArgsMergeMode;
+}
 export declare function toChatCompletionsMessage(message: ProviderMessage, options?: {
     reasoningContentEcho?: ReasoningContentEcho;
 }): Record<string, unknown>;
@@ -17,6 +21,11 @@ export interface ProviderInstanceOptions {
 }
 export declare function createUnavailableProvider(message: string): Provider;
 export declare function createProviderInstance(options: ProviderInstanceOptions): Provider;
+export interface NormalizedToolArgs {
+    args: string;
+    corrupt: boolean;
+}
+export declare function normalizeToolArgsDetailed(raw: string): NormalizedToolArgs;
 export declare function normalizeToolArgs(raw: string): string;
 /**
  * Convert an OpenAI-compatible chat-completions stream into our internal StreamChunk events.
@@ -26,5 +35,5 @@ export declare function normalizeToolArgs(raw: string): string;
  * partial write previews before the tool executes. End events are still flushed
  * in index order to keep multi-call turns deterministic.
  */
-export declare function translateOpenAIStream(stream: AsyncIterable<any>): AsyncIterable<StreamChunk>;
+export declare function translateOpenAIStream(stream: AsyncIterable<any>, options?: TranslateOpenAIStreamOptions): AsyncIterable<StreamChunk>;
 export {};