@vetala/vetala 0.5.4 → 0.5.6

package/README.md

@@ -27,55 +27,25 @@ Current provider support includes Sarvam AI and OpenRouter.
 
 ## Patch Notes
 
-### v0.5.4
+### v0.5.6
 Added:
-- Copy last reply action (Ctrl+Y) with a compact inline affordance after assistant replies.
-- Resume picker preview tuning and option line wrapping for tighter terminals.
+- Turn deliberation with dynamic reasoning effort, visible planning/thinking summaries, and live execution phases in the TUI footer.
+- Clarification-first behavior for underspecified edit requests through stronger `ask_user` guidance.
 
 Patched:
-- Repeat-tool warning injection with configurable threshold/message.
-- Empty-response warning when a model returns no content (env-tunable).
-- Default mouse mode enables in-app scroll wheel; can be disabled for terminal selection.
+- `Ctrl+C` pause flow now interrupts active tool/model work more reliably and shows an immediate stopping modal.
+- Repo-wide search cancellation now propagates through the TypeScript backend and Go TUI worker path.
+- Non-trivial turns now surface reasoning and phase state more clearly during execution.
 
-### v0.5.3
+### v0.5.5
 Added:
-- UI refresh: left-aligned layout with minimal framing.
-- Viewport-backed transcript with in-app scrollback (PgUp/PgDn + mouse wheel in-app mode).
-- Dynamic input bar with background styling and auto-resize.
-- UI hints + tool details toggle (Ctrl+T) plus env-tunable UI controls (mouse mode, alt screen, limits).
+- Deterministic skill routing with active-skill visibility in the UI.
+- Git-aware review flow upgrades with dedicated `/diff` and `/review` entry points.
 
 Patched:
-- Buffered output while modals are open to prevent UI jumps.
-- Live preview rendering is capped and separated from the transcript during streaming.
-- Cached Glamour renderer per theme/width to cut render cost.
-- Fast search skips binaries/oversized files and handles long lines safely.
-
-### v0.5.2
-Added:
-- `/resume` now skips empty sessions and previews the last few messages when resuming.
-- Workspace auto-resume uses the most recent non-empty session.
-
-Patched:
-- Resume selection list starts at the top and scrolls cleanly for longer lists.
-- Modal transitions no longer leave duplicate empty boxes.
-
-### v0.5.1
-Added:
-- New data layout: `memories/`, `rules/`, `snapshots/`, `logs/`, `tasks/`, and `history.jsonl`.
-- Background memory pipeline that writes `raw_memories.md`, rollout summaries, and a consolidated `MEMORY.md`.
-- Configurable memory/context/history limits (visible in `/config`).
-- Update notifier inside the TUI flow with “update now” or “skip for 24 hours”.
-
-Patched:
-- Update checks now run before the TUI trust prompt (and won’t duplicate when launched from the CLI).
-- History persistence trims safely to the configured size cap.
-
-### v0.5.0
-- **bugfix**: major bug fixes and performance improvements
-- **Universal Syntax Diagnostics**: Replaced the Python-only `compileall` fallback in `get_diagnostics` with `web-tree-sitter`. Vetala can now perform syntax checking across multiple languages (TypeScript, Python, Go, Rust, C, C++, Java, Ruby) directly in memory, even if you don't have the native compiler installed on your machine!
-- **Data-Driven Language Registry**: Centralized language management and file extension mapping. Adding new language support is now a single object definition.
-- **Smart Two-Tier Checks**: Diagnostics now try native tools first (`npx tsc`, `go build`) for the highest quality errors, and transparently fall back to WASM tree-sitter parsing if the toolchain is missing.
-
+- Malformed tool calls are quarantined before they can poison session history.
+- `Ctrl+C` can now stop active repo search work instead of waiting for long searches to finish.
+- Explicit file-path prompts now steer toward `read_file`/`read_file_chunk` before repo-wide search.
 
 ## Compatibility
 

package/dist/src/agent.d.ts

@@ -4,7 +4,16 @@ import { SessionStore } from "./session-store.js";
 import { TerminalUI } from "./terminal-ui.js";
 import { ToolRegistry } from "./tools/registry.js";
 import type { SkillRuntime } from "./skills/runtime.js";
-import type { EffectiveConfig, RuntimeHostProfile, SessionState } from "./types.js";
+import type { ChatMessage, EffectiveConfig, RuntimeHostProfile, SessionState, ToolCall } from "./types.js";
+export interface InvalidToolCall {
+    toolName: string;
+    rawArguments: string;
+    reason: string;
+}
+export interface ToolCallPartition {
+    validToolCalls: ToolCall[];
+    invalidToolCalls: InvalidToolCall[];
+}
 export interface AgentOptions {
     config: EffectiveConfig;
     session: SessionState;
@@ -21,13 +30,21 @@ export interface AgentOptions {
     fastSearch?: (query: string, root: string, options?: {
         limit?: number;
         regex?: boolean;
+        globs?: string[];
+        includeHidden?: boolean;
+        signal?: AbortSignal;
     }) => Promise<any[] | null>;
 }
 export declare class Agent {
     private readonly options;
     private readonly client;
     private activeRequestController;
+    private activeTurnController;
     private stopRequested;
+    private turnSkillPrompt;
+    private turnDeliberationPrompt;
+    private turnReasoningEffort;
+    private turnReasoningLabel;
     constructor(options: AgentOptions);
     get session(): SessionState;
     requestStop(): void;
@@ -46,3 +63,8 @@ export declare class AgentInterruptedError extends Error {
     constructor();
 }
 export declare function isAgentInterruptedError(error: unknown): error is AgentInterruptedError;
+export declare function partitionToolCalls(toolCalls: ToolCall[]): ToolCallPartition;
+export declare function sanitizeConversationMessages<T extends ChatMessage>(messages: T[]): {
+    messages: T[];
+    invalidToolCallCount: number;
+};

package/dist/src/agent.js

@@ -1,4 +1,5 @@
 import { compactConversation } from "./context-memory.js";
+import { analyzeTurnDeliberation, phaseForTool } from "./deliberation.js";
 import { loadMemoriesPrompt, loadRulesPrompt } from "./context-files.js";
 import { appendHistoryEntry } from "./history-store.js";
 import { createProviderClient, getProviderDefinition, providerLabel, withSystemMessage } from "./providers/index.js";
@@ -7,7 +8,12 @@ export class Agent {
     options;
     client;
     activeRequestController = null;
+    activeTurnController = null;
     stopRequested = false;
+    turnSkillPrompt = null;
+    turnDeliberationPrompt = null;
+    turnReasoningEffort = null;
+    turnReasoningLabel = "none";
     constructor(options) {
         this.options = options;
         this.client = createProviderClient(options.config.providers[options.session.provider]);
@@ -17,135 +23,208 @@ export class Agent {
     }
     requestStop() {
         this.stopRequested = true;
+        this.activeTurnController?.abort();
         this.activeRequestController?.abort();
     }
     async runTurn(userInput, streaming) {
+        const turnController = new AbortController();
+        this.activeTurnController = turnController;
         this.stopRequested = false;
-        const userMessage = this.persistedMessage({
-            role: "user",
-            content: userInput
-        });
-        await this.options.sessionStore.appendMessage(this.options.session, userMessage);
-        void appendHistoryEntry(this.options.config, this.options.session.id, userInput).catch(() => {
-            // Best-effort history persistence.
-        });
-        const localGreeting = maybeLocalGreeting(userInput);
-        if (localGreeting) {
-            await this.appendAndRenderAssistantMessage(localGreeting, false);
-            return;
-        }
-        const provider = this.options.config.providers[this.options.session.provider];
-        const providerDefinition = getProviderDefinition(this.options.session.provider);
-        if (!provider.authValue) {
-            const missingAuthMessage = provider.authSource === "stored_hash"
-                ? `A stored SHA-256 fingerprint exists for ${providerDefinition.label}, but the raw credential is not available in this process. Use /model to enter the key again or set ${providerDefinition.auth.envVars.join(", ")}.`
-                : `${providerDefinition.label} credentials are missing. Set ${providerDefinition.auth.envVars.join(", ")} and try again.`;
-            await this.appendAndRenderAssistantMessage(missingAuthMessage, false);
-            return;
-        }
-        const seenToolCalls = new Set();
-        let repeatWarningInjected = 0;
-        let consecutiveApiErrors = 0;
-        while (true) {
-            this.throwIfStopped();
-            const conversation = compactConversation(this.options.session.messages, this.options.session.referencedFiles, this.options.config.memory);
-            const recentCount = this.options.config.memory.recentMessageCount;
-            this.options.ui.activity(conversation.compactedCount > 0
-                ? `Using ${recentCount} recent messages and ${conversation.compactedCount} compacted earlier messages.`
-                : "Using the live conversation context.");
-            const systemPrompt = await this.systemPrompt(conversation.memory, conversation.compactedCount);
-            const requestMessages = withSystemMessage(systemPrompt, conversation.recentMessages);
-            let turn;
-            try {
-                turn = await this.completeTurn(requestMessages, streaming);
-                consecutiveApiErrors = 0; // Reset on success
-            }
-            catch (error) {
-                if (isAbortError(error) || error instanceof AgentInterruptedError) {
-                    this.options.ui.endAssistantTurn();
-                    throw new AgentInterruptedError();
-                }
-                consecutiveApiErrors += 1;
-                const errorMessage = error instanceof Error ? error.message : String(error);
-                if (consecutiveApiErrors >= 3) {
-                    await this.appendAndRenderAssistantMessage(`I've encountered multiple consecutive API errors and must stop. Last error: ${errorMessage}`, true);
-                    return;
-                }
-                this.options.ui.warn(`API Error: ${errorMessage}`);
-                this.options.ui.activity("Retrying automatically...");
-                const syntheticUserMessage = this.persistedMessage({
-                    role: "user",
-                    content: `SYSTEM ALERT: The previous generation failed with an API error: ${errorMessage}\nIf you were generating a large file, you likely hit the maximum output token limit. Please try breaking your response down, or use the append_to_file tool to write large files in chunks.`
-                });
-                await this.options.sessionStore.appendMessage(this.options.session, syntheticUserMessage);
-                continue;
-            }
-            const hasContent = typeof turn.content === "string" && turn.content.trim().length > 0;
-            if (!hasContent && turn.toolCalls.length === 0) {
-                if (emptyResponseWarningEnabled()) {
-                    this.options.ui.warn(emptyResponseWarningMessage());
-                }
-                this.options.ui.endAssistantTurn();
+        try {
+            const userMessage = this.persistedMessage({
+                role: "user",
+                content: userInput
+            });
+            await this.options.sessionStore.appendMessage(this.options.session, userMessage);
+            void appendHistoryEntry(this.options.config, this.options.session.id, userInput).catch(() => {
+                // Best-effort history persistence.
+            });
+            this.turnSkillPrompt = null;
+            this.options.ui.updateActiveSkills([]);
+            const localGreeting = maybeLocalGreeting(userInput);
+            if (localGreeting) {
+                await this.appendAndRenderAssistantMessage(localGreeting, false);
                 return;
             }
-            const assistantMessage = this.persistedMessage({
-                role: "assistant",
-                content: turn.content || null,
-                tool_calls: turn.toolCalls.length > 0 ? turn.toolCalls : null
+            const turnSkillContext = await this.options.skills.resolveTurnContext(userInput);
+            this.turnSkillPrompt = turnSkillContext.prompt;
+            this.options.ui.updateActiveSkills(turnSkillContext.labels);
+            const provider = this.options.config.providers[this.options.session.provider];
+            const providerDefinition = getProviderDefinition(this.options.session.provider);
+            const deliberation = analyzeTurnDeliberation(userInput, {
+                configuredEffort: providerDefinition.supportsReasoningEffort ? this.options.config.reasoningEffort : null,
+                activeSkills: turnSkillContext.labels
             });
-            await this.options.sessionStore.appendMessage(this.options.session, assistantMessage);
-            if (turn.toolCalls.length === 0) {
-                this.options.ui.endAssistantTurn();
+            this.turnDeliberationPrompt = deliberation.guidance;
+            this.turnReasoningEffort = providerDefinition.supportsReasoningEffort ? deliberation.reasoningEffort : null;
+            this.turnReasoningLabel = deliberation.reasoningLabel;
+            this.options.ui.updateTurnState(this.turnReasoningLabel, "planning");
+            if (deliberation.shouldShowThinking && deliberation.thinkingSummary) {
+                this.options.ui.printThinking(deliberation.thinkingSummary);
+            }
+            if (!provider.authValue) {
+                const missingAuthMessage = provider.authSource === "stored_hash"
+                    ? `A stored SHA-256 fingerprint exists for ${providerDefinition.label}, but the raw credential is not available in this process. Use /model to enter the key again or set ${providerDefinition.auth.envVars.join(", ")}.`
+                    : `${providerDefinition.label} credentials are missing. Set ${providerDefinition.auth.envVars.join(", ")} and try again.`;
+                await this.appendAndRenderAssistantMessage(missingAuthMessage, false);
                 return;
             }
-            let suppressedRepeats = 0;
-            for (const toolCall of turn.toolCalls) {
+            const seenToolCalls = new Set();
+            let repeatWarningInjected = 0;
+            let consecutiveApiErrors = 0;
+            let malformedToolCallRetries = 0;
+            let sanitizedHistoryWarningShown = false;
+            while (true) {
                 this.throwIfStopped();
-                this.options.ui.printToolCall(toolCall);
-                const signature = toolCallSignature(toolCall);
-                let result;
-                if (seenToolCalls.has(signature)) {
-                    suppressedRepeats += 1;
-                    this.options.ui.activity(`Skipping repeated ${toolCall.function.name} call.`);
-                    result = {
-                        summary: "Repeated tool call suppressed",
-                        content: "This exact tool call already ran earlier in this turn. Reuse the earlier result instead of calling it again.",
-                        isError: true
-                    };
+                const conversation = compactConversation(this.options.session.messages, this.options.session.referencedFiles, this.options.config.memory);
+                const sanitizedConversation = sanitizeConversationMessages(conversation.recentMessages);
+                const recentCount = this.options.config.memory.recentMessageCount;
+                this.options.ui.activity(conversation.compactedCount > 0
+                    ? `Using ${recentCount} recent messages and ${conversation.compactedCount} compacted earlier messages.`
+                    : "Using the live conversation context.");
+                if (sanitizedConversation.invalidToolCallCount > 0 && !sanitizedHistoryWarningShown) {
+                    sanitizedHistoryWarningShown = true;
+                    this.options.ui.activity(`Ignoring ${sanitizedConversation.invalidToolCallCount} malformed tool call${sanitizedConversation.invalidToolCallCount === 1 ? "" : "s"} from earlier session history.`);
+                }
+                const systemPrompt = await this.systemPrompt(conversation.memory, conversation.compactedCount);
+                const requestMessages = withSystemMessage(systemPrompt, sanitizedConversation.messages);
+                let turn;
+                try {
+                    turn = await this.completeTurn(requestMessages, streaming);
+                    consecutiveApiErrors = 0; // Reset on success
                 }
-                else {
-                    seenToolCalls.add(signature);
-                    this.options.ui.activity(`Running ${toolCall.function.name}.`);
-                    const toolSpec = this.options.tools.getTool(toolCall.function.name);
-                    const isMutating = toolSpec && !toolSpec.readOnly;
-                    result = await this.options.tools.execute(toolCall, this.toolContext());
-                    if (result.isError) {
-                        seenToolCalls.delete(signature);
+                catch (error) {
+                    if (isAbortError(error) || error instanceof AgentInterruptedError) {
+                        this.options.ui.endAssistantTurn();
+                        throw new AgentInterruptedError();
                     }
-                    else if (isMutating) {
-                        seenToolCalls.clear();
+                    consecutiveApiErrors += 1;
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    if (consecutiveApiErrors >= 3) {
+                        await this.appendAndRenderAssistantMessage(`I've encountered multiple consecutive API errors and must stop. Last error: ${errorMessage}`, true);
+                        return;
                     }
+                    this.options.ui.warn(`API Error: ${errorMessage}`);
+                    this.options.ui.activity("Retrying automatically...");
+                    const syntheticUserMessage = this.persistedMessage({
+                        role: "user",
+                        content: `SYSTEM ALERT: The previous generation failed with an API error: ${errorMessage}\nIf you were generating a large file, you likely hit the maximum output token limit. Please try breaking your response down, or use the append_to_file tool to write large files in chunks.`
+                    });
+                    await this.options.sessionStore.appendMessage(this.options.session, syntheticUserMessage);
+                    continue;
                 }
-                this.throwIfStopped();
-                this.options.ui.printToolResult(result.summary, result.isError);
-                await this.options.sessionStore.appendMessage(this.options.session, this.persistedMessage({
-                    role: "tool",
-                    content: result.content,
-                    tool_call_id: toolCall.id
-                }));
-            }
-            if (shouldInjectRepeatWarning(suppressedRepeats, repeatWarningInjected)) {
-                repeatWarningInjected += 1;
-                const warning = this.persistedMessage({
-                    role: "user",
-                    content: toolRepeatWarningMessage()
+                const hasContent = typeof turn.content === "string" && turn.content.trim().length > 0;
+                if (!hasContent && turn.toolCalls.length === 0) {
+                    if (emptyResponseWarningEnabled()) {
+                        this.options.ui.warn(emptyResponseWarningMessage());
+                    }
+                    this.options.ui.endAssistantTurn();
+                    return;
+                }
+                const partitionedToolCalls = partitionToolCalls(turn.toolCalls);
+                if (partitionedToolCalls.invalidToolCalls.length > 0) {
+                    malformedToolCallRetries += 1;
+                    if (hasContent) {
+                        await this.options.sessionStore.appendMessage(this.options.session, this.persistedMessage({
+                            role: "assistant",
+                            content: turn.content,
+                            tool_calls: null
+                        }));
+                    }
+                    const summary = summarizeInvalidToolCalls(partitionedToolCalls.invalidToolCalls);
+                    this.options.ui.warn(`Model emitted malformed tool arguments${summary ? `: ${summary}` : ""}. Retrying with smaller, valid tool calls.`);
+                    if (malformedToolCallRetries >= 3) {
+                        await this.appendAndRenderAssistantMessage(`The model kept emitting malformed tool calls and I stopped before making changes. Last issue: ${summary || "invalid tool arguments"}.`, true);
+                        return;
+                    }
+                    await this.options.sessionStore.appendMessage(this.options.session, this.persistedMessage({
+                        role: "user",
+                        content: malformedToolCallRepairPrompt(partitionedToolCalls.invalidToolCalls)
+                    }));
+                    continue;
+                }
+                malformedToolCallRetries = 0;
+                const assistantMessage = this.persistedMessage({
+                    role: "assistant",
+                    content: turn.content || null,
+                    tool_calls: partitionedToolCalls.validToolCalls.length > 0 ? partitionedToolCalls.validToolCalls : null
                 });
-                await this.options.sessionStore.appendMessage(this.options.session, warning);
+                await this.options.sessionStore.appendMessage(this.options.session, assistantMessage);
+                if (partitionedToolCalls.validToolCalls.length === 0) {
+                    this.options.ui.endAssistantTurn();
+                    return;
+                }
+                let suppressedRepeats = 0;
+                for (const toolCall of partitionedToolCalls.validToolCalls) {
+                    this.throwIfStopped();
+                    this.options.ui.printToolCall(toolCall);
+                    const signature = toolCallSignature(toolCall);
+                    let result;
+                    if (seenToolCalls.has(signature)) {
+                        suppressedRepeats += 1;
+                        this.options.ui.activity(`Skipping repeated ${toolCall.function.name} call.`);
+                        result = {
+                            summary: "Repeated tool call suppressed",
+                            content: "This exact tool call already ran earlier in this turn. Reuse the earlier result instead of calling it again.",
+                            isError: true
+                        };
+                    }
+                    else {
+                        seenToolCalls.add(signature);
+                        this.options.ui.updateTurnState(this.turnReasoningLabel, phaseForTool(toolCall.function.name));
+                        this.options.ui.activity(`Running ${toolCall.function.name}.`);
+                        const toolSpec = this.options.tools.getTool(toolCall.function.name);
+                        const isMutating = toolSpec && !toolSpec.readOnly;
+                        try {
+                            result = await this.options.tools.execute(toolCall, this.toolContext(turnController));
+                        }
+                        catch (error) {
+                            if (isAbortError(error) || error instanceof AgentInterruptedError) {
+                                this.options.ui.endAssistantTurn();
+                                throw new AgentInterruptedError();
+                            }
+                            throw error;
+                        }
+                        if (result.isError) {
+                            seenToolCalls.delete(signature);
+                        }
+                        else if (isMutating) {
+                            seenToolCalls.clear();
+                        }
+                    }
+                    this.throwIfStopped();
+                    this.options.ui.printToolResult(result.summary, result.isError, result.content);
+                    await this.options.sessionStore.appendMessage(this.options.session, this.persistedMessage({
+                        role: "tool",
+                        content: result.content,
+                        tool_call_id: toolCall.id
+                    }));
+                }
+                if (shouldInjectRepeatWarning(suppressedRepeats, repeatWarningInjected)) {
+                    repeatWarningInjected += 1;
+                    const warning = this.persistedMessage({
+                        role: "user",
+                        content: toolRepeatWarningMessage()
+                    });
+                    await this.options.sessionStore.appendMessage(this.options.session, warning);
+                }
+                this.options.ui.updateTurnState(this.turnReasoningLabel, "thinking");
+            }
+        }
+        finally {
+            if (this.activeTurnController === turnController) {
+                this.activeTurnController = null;
             }
+            this.turnSkillPrompt = null;
+            this.turnDeliberationPrompt = null;
+            this.turnReasoningEffort = null;
+            this.turnReasoningLabel = "none";
+            this.options.ui.updateTurnState(null, null);
         }
     }
     async completeTurn(messages, streaming) {
-        this.options.ui.activity(`Thinking with ${providerLabel(this.options.session.provider)} / ${this.options.session.model}.`);
+        this.options.ui.updateTurnState(this.turnReasoningLabel, "thinking");
+        this.options.ui.activity(`Thinking with ${providerLabel(this.options.session.provider)} / ${this.options.session.model} (${this.turnReasoningLabel} reasoning).`);
         const requestOptions = this.beginRequest();
         if (!streaming) {
             const spinner = this.options.ui.startSpinner("Thinking");
@@ -184,7 +263,7 @@ export class Agent {
                 this.options.ui.endAssistantTurn();
                 throw new AgentInterruptedError();
             }
-            this.options.ui.endAssistantTurn();
+            this.options.ui.discardAssistantDraft();
             this.options.ui.activity("Streaming failed. Retrying with buffered completion.");
             this.options.ui.warn(`Streaming failed, falling back to buffered completion: ${error instanceof Error ? error.message : String(error)}`);
             return this.completeTurn(messages, false);
@@ -199,16 +278,24 @@ export class Agent {
             model: this.options.session.model,
             temperature: 0.2,
             reasoning_effort: getProviderDefinition(this.options.session.provider).supportsReasoningEffort
-                ? this.options.config.reasoningEffort
+                ? this.turnReasoningEffort
                 : null,
             tools: this.options.tools.toSarvamTools(),
             tool_choice: "auto"
         };
     }
-    toolContext() {
+    toolContext(turnController) {
         return {
             cwd: process.cwd(),
             workspaceRoot: this.options.session.workspaceRoot,
+            lifecycle: {
+                signal: turnController.signal,
+                throwIfAborted: () => {
+                    if (turnController.signal.aborted || this.stopRequested) {
+                        throw new AgentInterruptedError();
+                    }
+                }
+            },
             approvals: {
                 requestApproval: (request) => this.options.approvals.requestApproval(request),
                 hasSessionGrant: (key) => this.options.approvals.hasSessionGrant(key),
@@ -221,7 +308,10 @@ export class Agent {
             },
             performance: {
                 computeDiff: (before, after) => this.options.computeDiff ? this.options.computeDiff(before, after) : Promise.resolve(null),
-                fastSearch: (query, root, opts) => this.options.fastSearch ? this.options.fastSearch(query, root, opts) : Promise.resolve(null)
+                fastSearch: (query, root, opts) => this.options.fastSearch ? this.options.fastSearch(query, root, {
+                    ...opts,
+                    signal: turnController.signal
+                }) : Promise.resolve(null)
             },
             reads: {
                 hasRead: (targetPath) => this.options.session.readFiles.includes(targetPath),
@@ -259,7 +349,6 @@ export class Agent {
     }
     async systemPrompt(memory, compactedCount) {
         const skillInventory = await this.options.skills.inventoryPrompt();
-        const pinnedSkillContext = await this.options.skills.pinnedPrompt();
         const [rulesPrompt, persistentMemory] = await Promise.all([
             loadRulesPrompt(this.options.config.contextFiles),
             this.options.config.memories.useMemories
@@ -282,6 +371,16 @@ export class Agent {
             `Active provider: ${providerLabel(this.options.session.provider)}`,
             `Active model: ${this.options.session.model}`,
             `Allowed roots right now: ${this.options.pathPolicy.allowedRoots().join(", ")}`,
+            "When using tools, emit valid JSON object arguments only.",
+            "Prefer smaller tool calls over giant payloads. Break large refactors and large apply_patch edits into multiple steps.",
+            "When the user names a concrete file path, read that file directly with read_file or read_file_chunk before considering search_repo.",
+            "For non-trivial tasks, form a concise plan before acting and execute it incrementally.",
+            "If the target, scope, or acceptance criteria remain unclear after initial inspection, use ask_user before editing.",
+            "For Git-aware tasks, prefer the dedicated git tools over ad-hoc shell commands.",
+            "For change review, start with git_review targeting the full worktree so you cover staged, unstaged, and untracked files.",
+            "For branch review, compare against the merge base with the requested base branch instead of assuming HEAD~1 or the previous commit.",
+            "Use git_log and git_blame when history or ownership helps explain why code exists.",
+            "Do not commit, push, or create branches unless the user explicitly asks.",
             compactedCount > 0
                 ? `Only the most recent messages are attached verbatim. ${compactedCount} earlier messages were compacted into working memory.`
                 : "The full conversation is attached because the session is still short."
@@ -290,8 +389,11 @@ export class Agent {
             lines.push("", rulesPrompt);
         }
         lines.push("", skillInventory);
-        if (pinnedSkillContext) {
-            lines.push("", pinnedSkillContext);
+        if (this.turnSkillPrompt) {
+            lines.push("", this.turnSkillPrompt);
+        }
+        if (this.turnDeliberationPrompt) {
+            lines.push("", this.turnDeliberationPrompt);
         }
         if (persistentMemory) {
             lines.push("", persistentMemory);
@@ -326,6 +428,58 @@ export class AgentInterruptedError extends Error {
 export function isAgentInterruptedError(error) {
     return error instanceof AgentInterruptedError;
 }
+export function partitionToolCalls(toolCalls) {
+    const validToolCalls = [];
+    const invalidToolCalls = [];
+    for (const toolCall of toolCalls) {
+        const toolName = toolCall.function.name.trim();
+        if (!toolName) {
+            invalidToolCalls.push({
+                toolName: "(unknown tool)",
+                rawArguments: toolCall.function.arguments,
+                reason: "Missing tool name."
+            });
+            continue;
+        }
+        const validationError = validateToolCallArguments(toolCall.function.arguments);
+        if (validationError) {
+            invalidToolCalls.push({
+                toolName,
+                rawArguments: toolCall.function.arguments,
+                reason: validationError
+            });
+            continue;
+        }
+        validToolCalls.push(toolCall);
+    }
+    return { validToolCalls, invalidToolCalls };
+}
+export function sanitizeConversationMessages(messages) {
+    const sanitized = [];
+    let invalidToolCallCount = 0;
+    for (const message of messages) {
+        if (message.role !== "assistant" || !message.tool_calls || message.tool_calls.length === 0) {
+            sanitized.push(message);
+            continue;
+        }
+        const partition = partitionToolCalls(message.tool_calls);
+        invalidToolCallCount += partition.invalidToolCalls.length;
+        if (partition.invalidToolCalls.length === 0) {
+            sanitized.push(message);
+            continue;
+        }
+        if ((message.content ?? "").trim() === "" && partition.validToolCalls.length === 0) {
+            continue;
+        }
+        const copy = { ...message };
+        delete copy.tool_calls;
+        if (partition.validToolCalls.length > 0) {
+            copy.tool_calls = partition.validToolCalls;
+        }
+        sanitized.push(copy);
+    }
+    return { messages: sanitized, invalidToolCallCount };
+}
 function toolCallSignature(toolCall) {
     try {
         return `${toolCall.function.name}:${JSON.stringify(JSON.parse(toolCall.function.arguments))}`;
@@ -369,6 +523,49 @@ function envBool(name) {
             return undefined;
     }
 }
+function validateToolCallArguments(rawArguments) {
+    if (!rawArguments.trim()) {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(rawArguments);
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return "Tool arguments must be a JSON object.";
+    }
+    return null;
+}
+function malformedToolCallRepairPrompt(invalidToolCalls) {
+    const tools = [...new Set(invalidToolCalls.map((issue) => issue.toolName))];
+    const lines = [
+        "SYSTEM ALERT: The previous assistant turn emitted malformed tool-call JSON, so those tools were not executed.",
+        `Affected tools: ${tools.join(", ")}.`,
+        "Retry the same intent, but emit valid JSON object arguments only.",
+        "Keep tool calls small and precise. Split large refactors or large apply_patch edits into multiple smaller tool calls."
+    ];
+    const applyPatchAffected = tools.some((name) => name === "apply_patch" || name === "replace_in_file");
+    if (applyPatchAffected) {
+        lines.push("For file edits, prefer smaller exact hunks with short search/replace blocks instead of one giant patch payload.");
+    }
+    const firstIssue = invalidToolCalls[0];
+    if (firstIssue) {
+        lines.push(`Last parse error: ${firstIssue.toolName}: ${firstIssue.reason}`);
+    }
+    lines.push("Continue the original request.");
+    return lines.join("\n");
+}
+function summarizeInvalidToolCalls(invalidToolCalls) {
+    const first = invalidToolCalls[0];
+    if (!first) {
+        return "";
+    }
+    const extra = invalidToolCalls.length - 1;
+    return `${first.toolName}: ${first.reason}${extra > 0 ? ` (+${extra} more)` : ""}`;
+}
 function envInt(name) {
     const raw = process.env[name];
     if (!raw) {