@nghyane/arcane 0.1.17 → 0.1.18

package/src/patch/edit-tool.ts

@@ -37,7 +37,6 @@ import {
 	type ReplaceTextEdit,
 } from "./hashline";
 import { detectLineEnding, normalizeToLF, restoreLineEndings, stripBom } from "./normalize";
-import { buildNormativeUpdateInput } from "./normative";
 import {
 	DEFAULT_EDIT_MODE,
 	type EditMode,
@@ -233,9 +232,9 @@ export class EditTool implements AgentTool<TInput, any, Theme> {
 		_toolCallId: string,
 		params: ReplaceParams | PatchParams | HashlineParams,
 		signal?: AbortSignal,
-		_onUpdate?: AgentToolUpdateCallback<EditToolDetails, TInput>,
+		_onUpdate?: AgentToolUpdateCallback<EditToolDetails>,
 		context?: AgentToolContext,
-	): Promise<AgentToolResult<EditToolDetails, TInput>> {
+	): Promise<AgentToolResult<EditToolDetails>> {
 		const batchRequest = getLspBatchRequest(context?.toolCall);
 
 		// ─────────────────────────────────────────────────────────────────
@@ -489,13 +488,6 @@ export class EditTool implements AgentTool<TInput, any, Theme> {
 			}
 			const diffResult = generateDiffString(originalNormalized, result.content);
 
-			const normative = buildNormativeUpdateInput({
-				path,
-				...(rename ? { rename } : {}),
-				oldContent: rawContent,
-				newContent: finalContent,
-			});
-
 			const meta = outputMeta()
 				.diagnostics(diagnostics?.summary ?? "", diagnostics?.messages ?? [])
 				.get();
@@ -516,7 +508,6 @@ export class EditTool implements AgentTool<TInput, any, Theme> {
 					rename,
 					meta,
 				},
-				$normative: normative,
 			};
 		}
 

package/src/prompts/agents/explore.md

@@ -5,7 +5,7 @@ tools: read, grep, find
 model: arcane/fast
 ---
 
-You are a fast, parallel code search agent.
+You are a fast, parallel code search agent running as a subagent inside an AI coding system. Your output goes directly to the main coding agent, not the end user. The main agent invokes you when it needs to locate code by behavior, concept, or multi-step search across the local codebase.
 
 ## Task
 Find files and line ranges relevant to the user's query (provided in the first message).
@@ -30,4 +30,6 @@ Before searching, decompose the query into:
 - Format each file as: `[relativePath#L{start}-L{end}](file://{absolutePath}#L{start}-L{end})`
 - **Use generous line ranges**: Extend ranges to capture complete logical units (full functions, classes, blocks). Add 5-10 lines buffer.
 
-Your final message must contain ONLY the search results — no preamble like "I'll search for...".
+<critical>
+Your final message must contain ONLY the search results — no preamble like "I'll search for...".
+</critical>

package/src/prompts/agents/librarian.md

@@ -6,7 +6,7 @@ model: arcane/fast
 thinking-level: minimal
 ---
 
-<role>Specialized remote repository understanding agent. Explore GitHub repositories, trace code flow across repos, explain architecture, find implementations, and surface relevant history.</role>
+<role>You are the Librarian, a specialized codebase understanding agent that helps answer questions about large, complex codebases across repositories. You are running as a subagent inside an AI coding system — your output goes directly to the main coding agent, not the end user. The main agent invokes you when it needs deep, multi-repository codebase understanding: architecture analysis, cross-repo code tracing, implementation discovery, and history exploration.</role>
 
 <directives>
 - Use the github tool for all repository operations — it handles auth, rate limits, and caching
@@ -16,16 +16,14 @@ thinking-level: minimal
 - Return repository paths (owner/repo + file path) for all referenced files
 </directives>
 
-<github>
+<instruction>
 Use the github tool for all GitHub API operations:
 - `github({ action: "get_file", ... })` for reading remote files
 - `github({ action: "get_tree", ... })` for listing directories
 - `github({ action: "get_issue", ... })` for reading issues with all comments
 - `github({ action: "get_pull", ... })` for PR details and diffs
 - `github({ action: "list_commits", ... })` for commit history
-</github>
 
-<search>
 Use search_code to find code across public GitHub repositories via grep.app:
 - `search_code({ query: "pattern" })` for broad cross-repo search
 - `search_code({ query: "pattern", repo: "owner/repo" })` for searching within a specific repo
@@ -33,7 +31,7 @@ Use search_code to find code across public GitHub repositories via grep.app:
 - Supports regex via `regexp: true`
 - Returns snippets with line numbers and match counts
 - No auth required, better snippets than GitHub Code Search API
-</search>
+</instruction>
 
 <procedure>
 1. Identify target repositories
@@ -59,4 +57,4 @@ Be comprehensive and direct. No filler.
 Only your final message is returned to the caller. It must be self-contained with all findings, paths, and explanations. Do not reference tool names or intermediate steps — present conclusions directly. Your final message must contain ONLY the information found — no preamble.
 
 Use "fluent" linking — embed file/PR/commit references in natural noun phrases, not raw URLs. Example: The [`handleAuth` function](file:///path/to/auth.ts#L42) validates tokens.
-</critical>
+</critical>

package/src/prompts/agents/reviewer.md

@@ -6,7 +6,7 @@ model: arcane/reviewer
 thinking-level: high
 ---
 
-<role>Senior engineer reviewing a proposed change. Identify bugs the author would want fixed before merge.</role>
+<role>You are a senior engineer reviewing a proposed change. You are running as a subagent inside an AI coding system — your output goes directly to the main coding agent, not the end user. The main agent invokes you to identify bugs the author would want fixed before merge.</role>
 
 <procedure>
 1. Run `git diff` (or `gh pr diff <number>`) to view patch

package/src/prompts/agents/task.md

@@ -18,5 +18,9 @@ Do the task end to end. Don’t hand back half-baked work.
 - Prefer edits to existing files over creating new ones. NEVER create documentation files (*.md) unless explicitly requested.
 - When done, write a concise summary of what you did as your final response. This is your output.
 - Use tools to get feedback on your generated code. Run diagnostics and type checks. If build/test commands aren’t known, find them in the environment.
-- Follow the main agent’s instructions and AGENTS.md conventions.
+- Follow the main agent's instructions and AGENTS.md conventions.
+
+<critical>
+Keep going until request is fully fulfilled. This matters.
+</critical>
 </directives>

package/src/prompts/system/system-prompt.md

@@ -1,5 +1,5 @@
 <identity>
-You are a distinguished staff engineer operating inside Arcane, a Pi-based coding harness.
+You are a distinguished staff engineer operating inside Arcane, a Pi-based coding harness. You are the main agent — you interact directly with the user and orchestrate subagents (explore, librarian, oracle, reviewer, task) for complex work.
 
 High-agency. Principled. Decisive.
 Correctness > politeness. Brevity > ceremony.
@@ -23,11 +23,16 @@ Balance initiative with predictability:
 </environment>
 
 ## Tool Usage
-- Use specialized tools instead of Bash for file operations.
+- Use specialized tools instead of Bash for file operations. Use read instead of `cat`/`head`/`tail`, edit instead of `sed`/`awk`, and write instead of echo redirection or heredoc. Reserve Bash for actual system commands.
 - Prefer doing work directly — you retain full context and produce better results.
 - Gather-then-act: collect all needed context first (parallel reads, greps, finds), then make changes. Do not interleave reading and editing one file at a time.
 - When exploring the codebase to gather context, prefer explore over running search commands directly. It reduces context usage and provides better results.
 
+## Editing Files
+- NEVER create files unless absolutely necessary for achieving the goal. ALWAYS prefer editing an existing file to creating a new one.
+- When changing an existing file, use edit. Only use write for files that do not exist yet.
+- Make the smallest reasonable diff. Do not rewrite whole files to change a few lines.
+
 ## Parallel Execution Policy
 Default to **parallel** for all independent work: reads, searches, diagnostics, writes to disjoint files, and subagents. Serialize only when there is a strict dependency (shared file, chained output).
 - Run multiple explore, oracle, or task calls in parallel when concerns are distinct.
@@ -134,6 +139,8 @@ You have three types of subagents (task, oracle, codebase search):
 - Use for: Feature scaffolding, cross-layer refactors, mass migrations, boilerplate generation, changes across many layers after planning.
 - Don't use for: Exploratory work, architectural decisions, debugging analysis, single logical task, reading a single file, editing a single file. Never spawn a single Task call for work you can do yourself.
 - Prompt it with detailed instructions on the goal, enumerate the deliverables, give it step by step procedures and ways to validate the results. Also give it constraints (e.g. coding style) and include relevant context snippets or examples.
+- Include the project's coding conventions relevant to the task — extract from AGENTS.md or surrounding code. Task agents do not internalize project-specific conventions; they rely on what you provide.
+- After a task completes, read its modified files to verify style and correctness. Do not trust task output blindly.
 
 #### Oracle
 - Senior engineering advisor with deep reasoning for reviews, architecture, deep debugging, and planning.
@@ -177,10 +184,7 @@ Tools: `find_thread`, `read_thread`, `save_memory`
 **save_memory**: only when user says "remember this" or states a clear preference. If unsure, ask.
 
 ### Verification
-After completing changes, verify using commands from AGENTS.md or the project's config. Format → typecheck/lint → test (if relevant) → build (if required).
-Report evidence concisely: counts, pass/fail, error summary.
-If unrelated pre-existing failures block you, say so and scope your change.
-Address all errors caused by your changes before yielding.
+Work incrementally. Make a small change, verify it works, then continue. Prefer a sequence of small, validated edits over one large change. Use commands from AGENTS.md or the project's config to verify. Address all errors caused by your changes before yielding.
 
 ### Concurrency Awareness
 You are not alone in the codebase. Others may edit concurrently.
@@ -199,7 +203,7 @@ Never run destructive git commands, bulk overwrites, or delete code you didn't w
 - Resolve blockers before yielding.
 </procedure>
 
-<contract>
+<critical>
 These are inviolable. Violation is system failure.
 1. Never claim unverified correctness. Verify the effect — confirm behavioral changes are observable.
 2. Never yield unless your deliverable is complete. Fix errors you introduced before yielding.
@@ -208,7 +212,10 @@ These are inviolable. Violation is system failure.
 5. Never solve the wished-for problem instead of the actual problem.
 6. Never ask for information obtainable from tools, repo context, or files.
 7. Full cutover within scope — update every call site. No backwards-compat shims.
-</contract>
+
+Keep going until fully resolved. This matters.
+</critical>
+
 
 <project>
 {{#if contextFiles.length}}

package/src/sdk.ts

@@ -930,16 +930,10 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		}
 	}
 
-	// Discover custom commands (TypeScript slash commands)
-	const customCommandsResult: CustomCommandsLoadResult = options.disableExtensionDiscovery
-		? { commands: [], errors: [] }
-		: await loadCustomCommandsInternal({ cwd, agentDir });
-	time("discoverCustomCommands");
-	if (!options.disableExtensionDiscovery) {
-		for (const { path, error } of customCommandsResult.errors) {
-			logger.error("Failed to load custom command", { path, error });
-		}
-	}
+	// Start custom commands discovery early (awaited later in parallel)
+	const customCommandsPromise = options.disableExtensionDiscovery
+		? Promise.resolve({ commands: [], errors: [] } as CustomCommandsLoadResult)
+		: loadCustomCommandsInternal({ cwd, agentDir });
 
 	let extensionRunner: ExtensionRunner | undefined;
 	if (extensionsResult.extensions.length > 0) {
@@ -1066,16 +1060,15 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		}
 	}
 
-	const systemPrompt = await rebuildSystemPrompt(initialToolNames, toolRegistry);
-	time("buildSystemPrompt");
-
-	const promptTemplates = options.promptTemplates ?? (await discoverPromptTemplates(cwd, agentDir));
-	time("discoverPromptTemplates");
+	const [systemPrompt, promptTemplates, slashCommands, customCommandsResult] = await Promise.all([
+		rebuildSystemPrompt(initialToolNames, toolRegistry),
+		options.promptTemplates ?? discoverPromptTemplates(cwd, agentDir),
+		options.slashCommands ?? discoverSlashCommands(cwd),
+		customCommandsPromise,
+	]);
+	time("buildSystemPrompt+discoverPromptTemplates+discoverSlashCommands");
 	toolSession.promptTemplates = promptTemplates;
 
-	const slashCommands = options.slashCommands ?? (await discoverSlashCommands(cwd));
-	time("discoverSlashCommands");
-
 	// Create convertToLlm wrapper that filters images if blockImages is enabled (defense-in-depth)
 	const convertToLlmWithBlockImages = (messages: AgentMessage[]): Message[] => {
 		const converted = convertToLlm(messages);

package/src/session/agent-session.ts

@@ -115,7 +115,6 @@ import {
 	maybeAbortStreamingEdit,
 	preCacheStreamingEditFile,
 	resetStreamingEditState,
-	rewriteToolCallArgs,
 } from "./streaming-edit";
 import {
 	addPendingTtsrInjections,
@@ -523,17 +522,12 @@ export class AgentSession {
 			}
 
 			if (event.message.role === "toolResult") {
-				const { toolName, $normative, toolCallId, details, isError, content } = event.message as {
+				const { toolName, details, isError, content } = event.message as {
 					toolName?: string;
-					toolCallId?: string;
 					details?: { path?: string };
-					$normative?: Record<string, unknown>;
 					isError?: boolean;
 					content?: Array<TextContent | ImageContent>;
 				};
-				if ($normative && toolCallId && this.settings.get("normativeRewrite")) {
-					await rewriteToolCallArgs(this.agent, this.sessionManager, toolCallId, $normative);
-				}
 				// Invalidate streaming edit cache when edit tool completes to prevent stale data
 				if (toolName === "edit" && details?.path) {
 					invalidateFileCacheForPath(this.#streamingEdit, details.path, this.sessionManager.getCwd());

package/src/session/session-manager.ts

@@ -1581,36 +1581,6 @@ export class SessionManager {
 		await this.#rewriteFile();
 	}
 
-	/**
-	 * Rewrite tool call arguments in the most recent assistant message containing the toolCallId.
-	 * Returns true if a tool call was updated.
-	 */
-	async rewriteAssistantToolCallArgs(toolCallId: string, args: Record<string, unknown>): Promise<boolean> {
-		let updated = false;
-		for (let i = this.#fileEntries.length - 1; i >= 0; i--) {
-			const entry = this.#fileEntries[i];
-			if (entry.type !== "message" || entry.message.role !== "assistant") continue;
-			const message = entry.message as { content?: unknown };
-			if (!Array.isArray(message.content)) continue;
-			for (const block of message.content) {
-				if (typeof block !== "object" || block === null) continue;
-				if (!("type" in block) || (block as { type?: string }).type !== "toolCall") continue;
-				const toolCall = block as { id?: string; arguments?: Record<string, unknown> };
-				if (toolCall.id === toolCallId) {
-					toolCall.arguments = args;
-					updated = true;
-					break;
-				}
-			}
-			if (updated) break;
-		}
-
-		if (updated && this.persist && this.#sessionFile) {
-			await this.#rewriteFile();
-		}
-		return updated;
-	}
-
 	/**
 	 * Append a custom message entry (for extensions) that participates in LLM context.
 	 * @param customType Hook identifier for filtering on reload

package/src/session/streaming-edit.ts

@@ -1,13 +1,12 @@
 import * as fs from "node:fs";
 
 import type { Agent, AgentEvent } from "@nghyane/arcane-agent";
-import type { AssistantMessage, ToolCall } from "@nghyane/arcane-ai";
+import type { ToolCall } from "@nghyane/arcane-ai";
 import { isEnoent, logger } from "@nghyane/arcane-utils";
 import type { Settings } from "../config/settings";
 import { normalizeDiff, normalizeToLF, ParseError, previewPatch, stripBom } from "../patch";
 import type { SecretObfuscator } from "../secrets/obfuscator";
 import { resolveToCwd } from "../tools/path-utils";
-import type { SessionManager } from "./session-manager";
 
 /**
  * Mutable state for streaming edit abort detection.
@@ -222,37 +221,3 @@ async function checkPreviewPatchAsync(
 		agent.abort();
 	}
 }
-
-/**
- * Rewrite tool call arguments in agent state and persisted session history.
- */
-export async function rewriteToolCallArgs(
-	agent: Agent,
-	sessionManager: SessionManager,
-	toolCallId: string,
-	args: Record<string, unknown>,
-): Promise<void> {
-	let updated = false;
-	const messages = agent.state.messages;
-	for (let i = messages.length - 1; i >= 0; i--) {
-		const msg = messages[i];
-		if (msg.role !== "assistant") continue;
-		const assistantMsg = msg as AssistantMessage;
-		if (!Array.isArray(assistantMsg.content)) continue;
-		for (const block of assistantMsg.content) {
-			if (typeof block !== "object" || block === null) continue;
-			if (!("type" in block) || (block as { type?: string }).type !== "toolCall") continue;
-			const toolCall = block as { id?: string; arguments?: Record<string, unknown> };
-			if (toolCall.id === toolCallId) {
-				toolCall.arguments = args;
-				updated = true;
-				break;
-			}
-		}
-		if (updated) break;
-	}
-
-	if (updated) {
-		await sessionManager.rewriteAssistantToolCallArgs(toolCallId, args);
-	}
-}

package/src/tools/bash.ts

@@ -55,7 +55,8 @@ function isInteractiveResult(result: BashResult | BashInteractiveResult): result
 export class BashTool implements AgentTool<typeof bashSchema, BashToolDetails, Theme> {
 	readonly name = "bash";
 	readonly label = "Bash";
-	description = "Execute a shell command";
+	description =
+		"Execute a shell command. Use grep/find instead of shell grep/find, read instead of cat/head/tail, edit instead of sed/awk, write instead of echo/printf redirects.";
 	readonly parameters = bashSchema;
 	readonly concurrency = "exclusive";
 

package/src/tools/create-tools.ts

@@ -1,7 +1,5 @@
 import type { AgentTool } from "@nghyane/arcane-agent";
-import { $env, logger } from "@nghyane/arcane-utils";
-import { getPreludeDocs, warmPythonEnvironment } from "../ipy/executor";
-import { checkPythonKernelAvailability } from "../ipy/kernel";
+import { $env } from "@nghyane/arcane-utils";
 import { LspTool } from "../lsp";
 import { EditTool } from "../patch";
 import { TaskTool } from "../task";
@@ -106,37 +104,8 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 	const enableLsp = session.enableLsp ?? true;
 	const requestedTools = toolNames && toolNames.length > 0 ? [...new Set(toolNames)] : undefined;
 	const pythonMode = getPythonModeFromEnv() ?? session.settings.get("python.toolMode");
-	const skipPythonPreflight = session.skipPythonPreflight === true;
-	let pythonAvailable = true;
-	const shouldCheckPython =
-		!skipPythonPreflight &&
-		pythonMode !== "bash-only" &&
-		(requestedTools === undefined || requestedTools.includes("python"));
-	const isTestEnv = Bun.env.BUN_ENV === "test" || Bun.env.NODE_ENV === "test";
-	const skipPythonWarm = isTestEnv || $env.ARCANE_PYTHON_SKIP_CHECK === "1";
-	if (shouldCheckPython) {
-		const availability = await checkPythonKernelAvailability(session.cwd);
-		time("createTools:pythonCheck");
-		pythonAvailable = availability.ok;
-		if (!availability.ok) {
-			logger.warn("Python kernel unavailable, falling back to bash", {
-				reason: availability.reason,
-			});
-		} else if (!skipPythonWarm && getPreludeDocs().length === 0) {
-			const sessionFile = session.getSessionFile?.() ?? undefined;
-			const warmSessionId = sessionFile ? `session:${sessionFile}:cwd:${session.cwd}` : `cwd:${session.cwd}`;
-			try {
-				await warmPythonEnvironment(session.cwd, warmSessionId, session.settings.get("python.sharedGateway"));
-				time("createTools:warmPython");
-			} catch (err) {
-				logger.warn("Failed to warm Python environment", {
-					error: err instanceof Error ? err.message : String(err),
-				});
-			}
-		}
-	}
 
-	const effectiveMode = pythonAvailable ? pythonMode : "bash-only";
+	const effectiveMode = pythonMode;
 	const allowBash = effectiveMode !== "ipy-only";
 	const allowPython = effectiveMode !== "bash-only";
 	if (

package/src/tools/fetch.ts

@@ -850,7 +850,7 @@ export interface FetchToolDetails {
 export class FetchTool implements AgentTool<typeof fetchSchema, FetchToolDetails, Theme> {
 	readonly name = "fetch";
 	readonly label = "Fetch";
-	description = "Fetch a URL and return its content";
+	description = "Fetch a URL and return its content. Do NOT use for localhost or local URLs; use bash curl instead.";
 	readonly parameters = fetchSchema;
 
 	constructor(private readonly session: ToolSession) {}

package/src/tools/grep.ts

@@ -54,7 +54,8 @@ type GrepParams = Static<typeof grepSchema>;
 export class GrepTool implements AgentTool<typeof grepSchema, GrepToolDetails, Theme> {
 	readonly name = "grep";
 	readonly label = "Grep";
-	description = "Search file contents with regex";
+	description =
+		"Search file contents with regex. Use for exact text matches (variable names, function calls, strings). Use explore for semantic/conceptual searches.";
 	readonly parameters = grepSchema;
 
 	constructor(private readonly session: ToolSession) {}

package/src/tools/python.ts

@@ -4,11 +4,13 @@ import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallb
 import type { ImageContent } from "@nghyane/arcane-ai";
 import type { Component } from "@nghyane/arcane-tui";
 import { Text } from "@nghyane/arcane-tui";
+import { $env, logger } from "@nghyane/arcane-utils";
 import { getProjectDir } from "@nghyane/arcane-utils/dirs";
 import { type Static, Type } from "@sinclair/typebox";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
-import { executePython, type PythonExecutorOptions } from "../ipy/executor";
+import { executePython, getPreludeDocs, type PythonExecutorOptions, warmPythonEnvironment } from "../ipy/executor";
 import type { PythonStatusEvent } from "../ipy/kernel";
+import { checkPythonKernelAvailability } from "../ipy/kernel";
 import { DEFAULT_MAX_BYTES, OutputSink, type OutputSummary } from "../session/streaming-output";
 import type { Theme } from "../theme/theme";
 import { renderCodeCell, renderStatusLine } from "../tui";
@@ -76,6 +78,8 @@ export class PythonTool implements AgentTool<typeof pythonSchema, any, Theme> {
 	readonly concurrency = "exclusive";
 
 	readonly #proxyExecutor?: PythonProxyExecutor;
+	#initialized = false;
+	#initPromise: Promise<void> | undefined;
 
 	constructor(
 		private readonly session: ToolSession | null,
@@ -84,6 +88,52 @@ export class PythonTool implements AgentTool<typeof pythonSchema, any, Theme> {
 		this.#proxyExecutor = options?.proxyExecutor;
 	}
 
+	async #ensureInitialized(): Promise<void> {
+		if (this.#initialized) return;
+		if (this.#initPromise) return this.#initPromise;
+		this.#initPromise = this.#doInit();
+		return this.#initPromise;
+	}
+
+	async #doInit(): Promise<void> {
+		try {
+			const isTestEnv = Bun.env.BUN_ENV === "test" || Bun.env.NODE_ENV === "test";
+			if (isTestEnv || $env.ARCANE_PYTHON_SKIP_CHECK === "1") {
+				this.#initialized = true;
+				return;
+			}
+			if (!this.session) {
+				this.#initialized = true;
+				return;
+			}
+			const availability = await checkPythonKernelAvailability(this.session.cwd);
+			if (!availability.ok) {
+				throw new ToolError(`Python kernel unavailable: ${availability.reason}`);
+			}
+			if (getPreludeDocs().length === 0) {
+				const sessionFile = this.session.getSessionFile?.() ?? undefined;
+				const warmSessionId = sessionFile
+					? `session:${sessionFile}:cwd:${this.session.cwd}`
+					: `cwd:${this.session.cwd}`;
+				try {
+					await warmPythonEnvironment(
+						this.session.cwd,
+						warmSessionId,
+						this.session.settings.get("python.sharedGateway"),
+					);
+				} catch (err) {
+					logger.warn("Failed to warm Python environment", {
+						error: err instanceof Error ? err.message : String(err),
+					});
+				}
+			}
+			this.#initialized = true;
+		} catch (err) {
+			this.#initPromise = undefined;
+			throw err;
+		}
+	}
+
 	async execute(
 		_toolCallId: string,
 		params: Static<typeof pythonSchema>,
@@ -99,6 +149,8 @@ export class PythonTool implements AgentTool<typeof pythonSchema, any, Theme> {
 			throw new ToolError("Python tool requires a session when not using proxy executor");
 		}
 
+		await this.#ensureInitialized();
+
 		const { cells, timeout: rawTimeout = 30, cwd, reset } = params;
 		// Clamp to reasonable range: 1s - 600s (10 min)
 		const timeoutSec = Math.max(1, Math.min(600, rawTimeout));

package/src/tools/read.ts

@@ -533,7 +533,8 @@ type ReadParams = ReadToolInput;
 export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails, Theme> {
 	readonly name = "read";
 	readonly label = "Read";
-	description = "Read file contents, list directories, or view images";
+	description =
+		"Read file contents, list directories, or view images. When possible, call in parallel for all files you need. Avoid tiny repeated slices — read a larger range instead.";
 	readonly parameters = readSchema;
 	readonly nonAbortable = true;
 

package/src/tools/write.ts

@@ -71,7 +71,7 @@ type WriteParams = WriteToolInput;
 export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails, Theme> {
 	readonly name = "write";
 	readonly label = "Write";
-	description = "Create a new file";
+	description = "Create a new file. For existing files, prefer edit instead — even for extensive changes.";
 	readonly parameters = writeSchema;
 	readonly nonAbortable = true;
 	readonly concurrency = "exclusive";

package/src/web/search/index.ts

@@ -265,7 +265,8 @@ export async function runSearchQuery(params: SearchParams): Promise<{
 export class SearchTool implements AgentTool<typeof webSearchSchema, SearchRenderDetails, Theme> {
 	readonly name = "web_search";
 	readonly label = "Web Search";
-	readonly description = "Search the web";
+	readonly description =
+		"Search the web for up-to-date information. Use fetch to read full content from a specific URL.";
 	readonly parameters = webSearchSchema;
 	readonly renderCall = renderSearchCall;
 	readonly renderResult = renderSearchResult;

package/src/patch/normative.ts

@@ -1,72 +0,0 @@
-/**
- * Normalize applied patch output into a canonical edit tool payload.
- */
-import { generateUnifiedDiffString } from "./diff";
-import { normalizeToLF, stripBom } from "./normalize";
-import { parseHunks } from "./parser";
-import type { PatchInput } from "./types";
-
-export interface NormativePatchOptions {
-	path: string;
-	rename?: string;
-	oldContent: string;
-	newContent: string;
-	contextLines?: number;
-	anchor?: string | string[];
-}
-
-/** Normative patch input is the MongoDB-style update variant */
-
-function applyAnchors(diff: string, anchors: Array<string | undefined> | undefined): string {
-	if (!anchors || anchors.length === 0) {
-		return diff;
-	}
-	const lines = diff.split("\n");
-	let anchorIndex = 0;
-	for (let i = 0; i < lines.length; i++) {
-		if (!lines[i].startsWith("@@")) continue;
-		const anchor = anchors[anchorIndex];
-		if (anchor !== undefined) {
-			lines[i] = anchor.trim().length === 0 ? "@@" : `@@ ${anchor}`;
-		}
-		anchorIndex++;
-	}
-	return lines.join("\n");
-}
-
-function deriveAnchors(diff: string): Array<string | undefined> {
-	const hunks = parseHunks(diff);
-	return hunks.map(hunk => {
-		if (hunk.oldLines.length === 0 || hunk.newLines.length === 0) {
-			return undefined;
-		}
-		const newLines = new Set(hunk.newLines);
-		for (const line of hunk.oldLines) {
-			const trimmed = line.trim();
-			if (trimmed.length === 0) continue;
-			if (!/[A-Za-z0-9_]/.test(trimmed)) continue;
-			if (newLines.has(line)) {
-				return trimmed;
-			}
-		}
-		return undefined;
-	});
-}
-
-export function buildNormativeUpdateInput(options: NormativePatchOptions): PatchInput {
-	const normalizedOld = normalizeToLF(stripBom(options.oldContent).text);
-	const normalizedNew = normalizeToLF(stripBom(options.newContent).text);
-	const diffResult = generateUnifiedDiffString(normalizedOld, normalizedNew, options.contextLines ?? 3);
-	let anchors: Array<string | undefined> | undefined =
-		typeof options.anchor === "string" ? [options.anchor] : options.anchor;
-	if (!anchors) {
-		anchors = deriveAnchors(diffResult.diff);
-	}
-	const diff = applyAnchors(diffResult.diff, anchors);
-	return {
-		path: options.path,
-		op: "update",
-		rename: options.rename,
-		diff,
-	};
-}