@ruvnet/open-claude-code 2.1.2-nightly.20261011.203 → 2.1.3

package/README.md

@@ -91,6 +91,28 @@ node scripts/plugin-e2e.mjs ruvnet/open-claude-code
 
 The suite installs and removes real skills and plugins in disposable profiles, checks all three Claude skill expansions with a local model fixture, and verifies OCC discovery. Live provider behavior is tested separately by `scripts/live-package-e2e.mjs`. Tested installer: skills 1.7.2; Claude Code: 2.1.283.
 
+
+## Upstream behavior fixes in 2.1.3
+
+Implemented and tested against the public [Claude Code 2.1.295 and 2.1.296 changelog](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md):
+
+| Behavior | OCC support |
+| --- | --- |
+| Hook failure policy | Command and HTTP hooks honor `onFailure: "block"`; exit 2 vetoes execution |
+| PreToolUse veto | `continue: false` and structured deny block the call and return an error result to the next model turn |
+| PostToolUse MCP output | `updatedMCPToolOutput` replaces results for MCP tool names |
+| Large text reads | `Read.allow_large: true` bypasses the implicit 2,000 line limit; explicit offset/limit remain active |
+| Encoding safety | Edit, MultiEdit and NotebookEdit reject invalid UTF8 before any write |
+| Delegation safety | Child tools intersect parent tools and inherit permission checks and hooks |
+| Model call budget | `--max-turns` limits model requests, including tool continuations |
+
+Large text reads have hard ceilings of 16 MiB and 100,000 lines. HTTP hook responses have a 1 MiB limit. Typed hook timeouts use seconds; legacy flat hook timeouts retain milliseconds. Plain command stdout remains supported.
+
+Subagents default to at most 10 model calls, delegation depth 2 (hard maximum 3), and at most 4 running background agents. An explicit empty child tool list grants no tools. Worktree isolation requests are rejected until isolation is implemented.
+
+Prompt and agent hook evaluators, asynchronous hooks, complete session/checkpoint lifecycle wiring, and full provider parity remain outside this release. See [ADR-006](docs/adr/ADR-006-upstream-behavioral-contracts.md). The [lifecycle issue](https://github.com/ruvnet/open-claude-code/issues/17) remains open for those gaps.
+
+
 ## 🧠 What Is This?
 
 **Open Claude Code** is a ground-up open source rebuild of Anthropic's [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code), informed by [ruDevolution's](https://github.com/ruvnet/rudevolution) AI-powered decompilation of the published npm package.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ruvnet/open-claude-code",
-  "version": "2.1.2-nightly.20261011.203",
+  "version": "2.1.3",
   "description": "Open source agentic coding CLI with verified nightly upstream analysis",
   "type": "module",
   "bin": {

package/src/core/agent-loop.mjs

@@ -18,9 +18,12 @@ export function createAgentLoop({ model, tools, permissions, settings, hooks, ca
             throw new TypeError(key + ' must be an array of nonempty tool names');
         }
     }
+    if (settings.maxTurns != null && (!Number.isSafeInteger(settings.maxTurns) || settings.maxTurns < 1)) {
+        throw new TypeError('maxTurns must be a positive safe integer');
+    }
     const allowedNames = new Set(settings.allowedTools || []);
     const deniedNames = new Set(settings.disallowedTools || []);
-    const toolAllowed = name => !deniedNames.has(name) &&
+    const toolAllowed = name => tools.has?.(name) !== false && !deniedNames.has(name) &&
         (allowedNames.size === 0 || allowedNames.has(name));
     const availableTools = () => (tools.list?.() || []).filter(tool => toolAllowed(tool.name));
 
@@ -66,6 +69,7 @@ export function createAgentLoop({ model, tools, permissions, settings, hooks, ca
     }
 
     async function* run(userMessage, options = {}) {
+        if (!options.continuation) state.modelCallCount = 0;
         const depth = (options._depth || 0);
 
         // Guard against runaway tool-call recursion
@@ -101,7 +105,7 @@ export function createAgentLoop({ model, tools, permissions, settings, hooks, ca
         }
 
         // Check max turns
-        if (settings.maxTurns && state.turnCount > settings.maxTurns) {
+        if (settings.maxTurns && state.modelCallCount >= settings.maxTurns) {
             yield { type: 'error', message: `Max turns (${settings.maxTurns}) reached.` };
             yield { type: 'stop', reason: 'max_turns' };
             return;
@@ -113,6 +117,7 @@ export function createAgentLoop({ model, tools, permissions, settings, hooks, ca
             state.messages = contextManager.compact(state.messages);
         }
 
+        state.modelCallCount++;
         yield { type: 'stream_request_start', turn: state.turnCount };
 
         // Detect provider and call API. Use state.model so an opt-in cascade
@@ -207,6 +212,7 @@ export function createAgentLoop({ model, tools, permissions, settings, hooks, ca
                         toolResults.push({
                             type: 'tool_result',
                             tool_use_id: block.id,
+                            is_error: true,
                             content: `Blocked by hook: ${hookResult.message}`,
                         });
                         continue;
@@ -220,6 +226,7 @@ export function createAgentLoop({ model, tools, permissions, settings, hooks, ca
                     toolResults.push({
                         type: 'tool_result',
                         tool_use_id: block.id,
+                        is_error: true,
                         content: 'Permission denied',
                     });
                     continue;
@@ -229,9 +236,15 @@ export function createAgentLoop({ model, tools, permissions, settings, hooks, ca
                 yield { type: 'tool_progress', tool: block.name, status: 'running' };
 
                 let result;
+                let toolFailed = false;
                 try {
-                    result = await tools.call(block.name, block.input);
+                    result = await tools.call(block.name, block.input, {
+                        permissions, settings, hooks, model: activeModel,
+                        allowedToolNames: availableTools().map(tool => tool.name),
+                        delegationDepth: settings.delegationDepth || 0,
+                    });
                 } catch (err) {
+                    toolFailed = true;
                     result = `Tool error: ${err.message}`;
                 }
 
@@ -245,6 +258,7 @@ export function createAgentLoop({ model, tools, permissions, settings, hooks, ca
                 toolResults.push({
                     type: 'tool_result',
                     tool_use_id: block.id,
+                    ...(toolFailed ? { is_error: true } : {}),
                     content: typeof result === 'string' ? result : JSON.stringify(result),
                 });
             }

package/src/hooks/engine.mjs

@@ -1,170 +1,159 @@
 /**
- * Hook Engine — pre/post tool use and stop hooks.
- *
- * Based on Claude Code's hooks system (6 event types):
- * - PreToolUse: can block tool execution
- * - PostToolUse: can modify results
- * - Stop: can prevent the agent from stopping
- * - Notification: inform external systems
- * - PrePrompt: modify user input
- * - PostResponse: modify assistant output
- *
- * Hooks are defined in settings.json under the "hooks" key.
+ * Hook Engine: command, HTTP and function hooks for pre/post tool use and stop.
+ * Legacy flat hooks retain millisecond timeouts and environment input.
+ * Claude-style typed hooks use second timeouts and JSON stdin/POST input.
+ * Prompt and agent evaluators are not supported.
  */
-
-import { execSync } from 'child_process';
+import { execSync, execFileSync } from 'node:child_process';
 
 export class HookEngine {
-    /**
-     * @param {object} hooksConfig - hooks configuration from settings
-     */
-    constructor(hooksConfig = {}) {
-        this.hooks = hooksConfig;
-    }
+    constructor(hooksConfig = {}) { this.hooks = hooksConfig; }
 
-    /**
-     * Run pre-tool-use hooks. Returns { allow, message }.
-     * If any hook returns deny, the tool call is blocked.
-     *
-     * @param {string} toolName - name of the tool being called
-     * @param {object} input - tool input arguments
-     * @returns {Promise<{allow: boolean, message?: string}>}
-     */
     async runPreToolUse(toolName, input) {
-        const hooks = this._getHooks('PreToolUse');
-        for (const hook of hooks) {
-            // Check if hook applies to this tool
-            if (hook.toolName && hook.toolName !== toolName) continue;
-
-            const result = await this._executeHook(hook, {
-                event: 'PreToolUse',
-                toolName,
-                input,
-            });
-
-            if (result?.decision === 'deny' || result?.decision === 'block') {
-                return { allow: false, message: result.message || `Blocked by hook: ${hook.name || 'unnamed'}` };
+        for (const hook of this._getHooks('PreToolUse', toolName)) {
+            const result = await this._executeHook(hook, { event: 'PreToolUse', toolName, input });
+            const specific = result?.hookSpecificOutput;
+            if (result?.continue === false || ['deny', 'block'].includes(result?.decision)
+                || specific?.permissionDecision === 'deny') {
+                return { allow: false, message: result.stopReason || result.message || result.reason
+                    || specific?.permissionDecisionReason || `Blocked by hook: ${hook.name || 'unnamed'}` };
             }
         }
         return { allow: true };
     }
 
-    /**
-     * Run post-tool-use hooks. Can modify the result.
-     *
-     * @param {string} toolName - name of the tool that was called
-     * @param {*} result - tool execution result
-     * @returns {Promise<*>} possibly modified result
-     */
     async runPostToolUse(toolName, result) {
-        const hooks = this._getHooks('PostToolUse');
         let current = result;
-        for (const hook of hooks) {
-            if (hook.toolName && hook.toolName !== toolName) continue;
-
-            const hookResult = await this._executeHook(hook, {
-                event: 'PostToolUse',
-                toolName,
-                result: current,
-            });
-
-            if (hookResult?.modifiedResult !== undefined) {
-                current = hookResult.modifiedResult;
-            }
+        for (const hook of this._getHooks('PostToolUse', toolName)) {
+            const output = await this._executeHook(hook, { event: 'PostToolUse', toolName, result: current });
+            const specific = output?.hookSpecificOutput;
+            if (output?.modifiedResult !== undefined) current = output.modifiedResult;
+            if (toolName.startsWith('mcp__') && specific?.updatedMCPToolOutput !== undefined)
+                current = specific.updatedMCPToolOutput;
         }
         return current;
     }
 
-    /**
-     * Run stop hooks. Returns true if stop should proceed, false to continue.
-     *
-     * @returns {Promise<boolean>} whether to allow stopping
-     */
     async runStop() {
-        const hooks = this._getHooks('Stop');
-        for (const hook of hooks) {
+        for (const hook of this._getHooks('Stop')) {
             const result = await this._executeHook(hook, { event: 'Stop' });
-            if (result?.preventStop) {
-                return false; // do not stop
-            }
+            if (result?.preventStop || result?.decision === 'block') return false;
         }
-        return true; // allow stop
+        return true;
     }
 
-    /**
-     * Run notification hooks (fire-and-forget).
-     * @param {string} event - notification event name
-     * @param {object} data - event data
-     */
     async runNotification(event, data) {
-        const hooks = this._getHooks('Notification');
-        for (const hook of hooks) {
-            try {
-                await this._executeHook(hook, { event, ...data });
-            } catch {
-                // Notifications are best-effort
+        for (const hook of this._getHooks('Notification')) {
+            try { await this._executeHook(hook, { event, ...data }); } catch { /* best effort */ }
+        }
+    }
+
+    _getHooks(eventType, toolName) {
+        const configured = this.hooks?.[eventType];
+        const entries = Array.isArray(configured) ? configured : configured ? [configured] : [];
+        return entries.flatMap(entry => {
+            if (entry.toolName && entry.toolName !== toolName) return [];
+            if (entry.matcher && toolName) {
+                try { if (!new RegExp(entry.matcher).test(toolName)) return []; }
+                catch {
+                    return (Array.isArray(entry.hooks) ? entry.hooks : [entry]).map(hook => ({
+                        onFailure: hook.onFailure, failOpen: hook.failOpen,
+                        handler: () => { throw new Error('Invalid hook matcher'); },
+                    }));
+                }
             }
+            return Array.isArray(entry.hooks) ? entry.hooks : [entry];
+        });
+    }
+
+    _timeout(hook) {
+        const value = hook.timeout === undefined ? 10000 : Number(hook.timeout) * (hook.type ? 1000 : 1);
+        if (!Number.isFinite(value) || value <= 0) throw new Error('Invalid hook timeout');
+        return Math.ceil(value);
+    }
+
+    _parseOutput(text, http = false) {
+        const trimmed = text.trim();
+        if (!trimmed) return null;
+        let output;
+        try { output = JSON.parse(trimmed); }
+        catch {
+            if (http || /^[\[{]/.test(trimmed)) throw new Error('Invalid hook JSON');
+            return { output: trimmed };
         }
+        if (!output || typeof output !== 'object' || Array.isArray(output)) throw new Error('Invalid hook output object');
+        for (const key of ['continue', 'preventStop']) {
+            if (output[key] !== undefined && typeof output[key] !== 'boolean') throw new Error('Invalid hook decision');
+        }
+        if (output.decision !== undefined && !['allow', 'deny', 'block', 'approve'].includes(output.decision))
+            throw new Error('Invalid hook decision');
+        const specific = output.hookSpecificOutput;
+        if (specific !== undefined && (!specific || typeof specific !== 'object' || Array.isArray(specific)))
+            throw new Error('Invalid hook-specific output');
+        if (specific?.permissionDecision !== undefined && !['allow', 'deny', 'ask'].includes(specific.permissionDecision))
+            throw new Error('Invalid hook permission decision');
+        return output;
     }
 
-    /**
-     * Get hooks for a given event type.
-     * @param {string} eventType
-     * @returns {Array}
-     */
-    _getHooks(eventType) {
-        if (!this.hooks || !this.hooks[eventType]) return [];
-        const hooks = this.hooks[eventType];
-        return Array.isArray(hooks) ? hooks : [hooks];
+    async _readHTTPResponse(response) {
+        if (!response.body) return '';
+        const reader = response.body.getReader();
+        const chunks = [];
+        let size = 0;
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done) break;
+                size += value.byteLength;
+                if (size > 1024 * 1024) {
+                    await reader.cancel('Hook response exceeds 1 MiB');
+                    throw new Error('Hook response exceeds 1 MiB');
+                }
+                chunks.push(value);
+            }
+            return Buffer.concat(chunks, size).toString('utf-8');
+        } finally {
+            reader.releaseLock();
+        }
     }
 
-    /**
-     * Execute a single hook. Supports command (shell) and function hooks.
-     *
-     * Note: hook.command is an operator-configured shell string (defined in
-     * settings.json by the user who controls this machine) — it is intentionally
-     * executed as a shell command.  The tool input/context is passed ONLY via
-     * environment variables (never interpolated into the command string) to
-     * prevent escalation from tool input into the hook command itself.
-     *
-     * @param {object} hook - hook definition
-     * @param {object} context - execution context
-     * @returns {Promise<object|null>}
-     */
     async _executeHook(hook, context) {
         try {
+            const timeout = this._timeout(hook);
+            const payload = { ...context, hook_event_name: context.event, tool_name: context.toolName,
+                tool_input: context.input, tool_response: context.result };
+            if (hook.type === 'http') {
+                const allowed = new Set(hook.allowedEnvVars || []);
+                const headers = Object.fromEntries(Object.entries(hook.headers || {}).map(([key, value]) =>
+                    [key, String(value).replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g,
+                        (_, braced, plain) => allowed.has(braced || plain) ? process.env[braced || plain] || '' : '')]));
+                const response = await fetch(hook.url, { method: 'POST', redirect: 'error',
+                    headers: { ...headers, 'Content-Type': 'application/json' },
+                    body: JSON.stringify(payload), signal: AbortSignal.timeout(timeout) });
+                if (!response.ok) throw new Error(`HTTP hook status ${response.status}`);
+                return this._parseOutput(await this._readHTTPResponse(response), true);
+            }
             if (hook.command) {
-                // Ensure env values are strings (guards against prototype pollution
-                // or non-string values from context objects breaking child_process).
-                const env = {
-                    ...process.env,
-                    HOOK_EVENT: String(context.event || ''),
-                    HOOK_TOOL: String(context.toolName || ''),
-                    HOOK_INPUT: JSON.stringify(context.input || {}),
-                };
-                const output = execSync(hook.command, {
-                    encoding: 'utf-8',
-                    timeout: hook.timeout || 10000,
-                    env,
-                });
-                try {
-                    return JSON.parse(output.trim());
-                } catch {
-                    return { output: output.trim() };
-                }
+                const options = { encoding: 'utf-8', timeout,
+                    input: JSON.stringify(payload), stdio: ['pipe', 'pipe', 'pipe'],
+                    env: { ...process.env, HOOK_EVENT: String(context.event || ''),
+                        HOOK_TOOL: String(context.toolName || ''), HOOK_INPUT: JSON.stringify(context.input || {}) } };
+                const output = Array.isArray(hook.args) ? execFileSync(hook.command, hook.args, options)
+                    : execSync(hook.command, options);
+                return this._parseOutput(output);
             }
-
             if (typeof hook.handler === 'function') {
                 return await hook.handler(context);
             }
-
+            if (hook.type || hook.onFailure === 'block') throw new Error('Unsupported hook definition');
             return null;
         } catch (err) {
-            if (hook.failOpen !== false) {
-                // Default: fail open (allow)
-                return null;
-            }
-            return { decision: 'deny', message: `Hook error: ${err.message}` };
+            // Exit 2 is an explicit veto, regardless of the configured failure mode.
+            if (err.status === 2) return { decision: context.event === 'Stop' ? 'block' : 'deny', message: 'Hook blocked action (exit 2)' };
+            // Stop failure must not create an endless retry loop.
+            if (context.event !== 'Stop' && (hook.onFailure === 'block' || hook.failOpen === false))
+                return { decision: 'deny', message: 'Hook failed; action blocked by failure policy' };
+            return null;
         }
     }
 }

package/src/tools/agent.mjs

@@ -3,13 +3,12 @@
  *
  * Features:
  * - subagent_type parameter
- * - isolation: "worktree" option
+ * - worktree isolation is rejected until implemented
  * - run_in_background option
  * - model override
  */
 
 import { createAgentLoop } from '../core/agent-loop.mjs';
-import { createToolRegistry } from './registry.mjs';
 import { createPermissionChecker } from '../permissions/checker.mjs';
 
 export const AgentTool = {
@@ -25,7 +24,7 @@ export const AgentTool = {
             allowed_tools: {
                 type: 'array',
                 items: { type: 'string' },
-                description: 'List of tool names the subagent can use (default: all)',
+                description: 'Subset of parent tools the subagent can use (default: inherited tools)',
             },
             subagent_type: {
                 type: 'string',
@@ -34,7 +33,7 @@ export const AgentTool = {
             isolation: {
                 type: 'string',
                 enum: ['default', 'worktree'],
-                description: 'Isolation mode. "worktree" uses a git worktree.',
+                description: 'Isolation mode. Worktree requests are currently rejected.',
             },
             run_in_background: {
                 type: 'boolean',
@@ -50,7 +49,8 @@ export const AgentTool = {
 
     validateInput(input) {
         const errors = [];
-        if (!input.prompt) errors.push('prompt is required');
+        if (typeof input?.prompt !== 'string' || !input.prompt.trim()) errors.push('prompt is required');
+        if (input?.allowed_tools !== undefined && (!Array.isArray(input.allowed_tools) || !input.allowed_tools.every(n => typeof n === 'string'))) errors.push('allowed_tools must be an array of tool names');
         return errors;
     },
 
@@ -58,10 +58,15 @@ export const AgentTool = {
     _backgroundAgents: new Map(),
     _nextBgId: 0,
 
-    async call(input) {
-        const model = input.model || process.env.SUBAGENT_MODEL || 'claude-sonnet-4-6';
-        const tools = createToolRegistry();
-        const permissions = createPermissionChecker({ defaultMode: 'bypassPermissions' });
+    async call(input, context = {}) {
+        const errors = AgentTool.validateInput(input);
+        if (errors.length) throw new Error(errors.join(', '));
+        if (input.isolation && input.isolation !== 'default') throw new Error('Subagent worktree isolation is not implemented.');
+        const { createToolRegistry } = await import('./registry.mjs');
+        const policy = createSubagentPolicy(input, context, createToolRegistry());
+        const model = input.model || context.model || process.env.SUBAGENT_MODEL || 'claude-sonnet-4-6';
+        const { tools, permissions } = policy;
+        if (input.run_in_background && [...AgentTool._backgroundAgents.values()].filter(a => a.status === 'running').length >= 4) throw new Error('Background subagent concurrency limit reached.');
 
         // Build type-specific system prompt prefix
         let systemPrefix = '';
@@ -84,7 +89,8 @@ export const AgentTool = {
             model,
             tools,
             permissions,
-            settings: { stream: false },
+            settings: policy.settings,
+            hooks: policy.hooks,
         });
 
         if (input.run_in_background) {
@@ -115,6 +121,7 @@ async function runSubagent(loop, prompt) {
             if (event.type === 'assistant' && event.content) {
                 results.push(event.content);
             }
+            if (event.type === 'error') throw new Error(event.message || 'Subagent failed');
             if (event.type === 'result') {
                 results.push(`[tool:${event.tool}] ${String(event.result).slice(0, 500)}`);
             }
@@ -125,3 +132,61 @@ async function runSubagent(loop, prompt) {
 
     return results.join('\n') || 'Subagent completed with no output.';
 }
+
+const SAFE_STANDALONE_TOOLS = ['Read', 'Glob', 'Grep', 'LS'];
+const MAX_CHILD_TURNS = 10;
+const MAX_DELEGATION_DEPTH = 3;
+
+/** Child capabilities are an intersection, never a fresh grant. */
+export function createSubagentPolicy(input, context = {}, registry) {
+    const errors = AgentTool.validateInput(input);
+    if (errors.length) throw new Error(errors.join(', '));
+    if (input.isolation && input.isolation !== 'default') {
+        throw new Error('Subagent worktree isolation is not implemented; refusing to run without isolation.');
+    }
+    const depth = context.delegationDepth ?? 0;
+    const maxDepth = Math.min(context.settings?.maxDelegationDepth ?? 2, MAX_DELEGATION_DEPTH);
+    if (!Number.isInteger(depth) || depth < 0 || !Number.isInteger(maxDepth) || depth >= maxDepth) {
+        throw new Error('Subagent delegation depth limit reached.');
+    }
+    const inheritedNames = context.allowedToolNames ?? SAFE_STANDALONE_TOOLS;
+    if (!Array.isArray(inheritedNames) || !inheritedNames.every(n => typeof n === 'string')) {
+        throw new Error('Invalid parent tool policy.');
+    }
+    const requested = new Set(input.allowed_tools ?? inheritedNames);
+    const allowed = new Set(inheritedNames.filter(name => requested.has(name) && registry.has(name)));
+    const parentPermissions = context.permissions ?? createPermissionChecker({ defaultMode: 'plan' });
+    if (typeof parentPermissions.check !== 'function') throw new Error('Invalid parent permission checker.');
+    const childContext = {
+        ...context,
+        allowedToolNames: [...allowed],
+        delegationDepth: depth + 1,
+        settings: {
+            ...context.settings,
+            stream: false,
+            allowedTools: [...allowed],
+            maxTurns: Math.min(context.settings?.maxTurns || MAX_CHILD_TURNS, MAX_CHILD_TURNS),
+            maxDelegationDepth: maxDepth,
+            delegationDepth: depth + 1,
+        },
+    };
+    const permissions = {
+        mode: parentPermissions.mode,
+        async check(name, toolInput) {
+            return allowed.has(name) && await parentPermissions.check(name, toolInput) === true;
+        },
+    };
+    childContext.permissions = permissions;
+    const tools = {
+        list: () => registry.list().filter(tool => allowed.has(tool.name)),
+        has: name => allowed.has(name),
+        get: name => allowed.has(name) ? registry.get(name) : undefined,
+        async call(name, toolInput) {
+            if (!await permissions.check(name, toolInput)) throw new Error('Subagent tool denied: ' + name);
+            // Explicit context propagation also works with older registry dispatchers.
+            if (name === 'Agent') return AgentTool.call(toolInput, childContext);
+            return registry.call(name, toolInput, childContext);
+        },
+    };
+    return { ...childContext, tools, permissions };
+}

package/src/tools/edit.mjs

@@ -9,6 +9,7 @@
  */
 import fs from 'fs';
 import path from 'path';
+import { readStrictUtf8 } from './text-encoding.mjs';
 import { hasBeenRead, markRead } from './read.mjs';
 
 export const EditTool = {
@@ -46,7 +47,7 @@ export const EditTool = {
 
         let content;
         try {
-            content = fs.readFileSync(filePath, 'utf-8');
+            content = readStrictUtf8(filePath);
         } catch (e) {
             return `Error: ${e.message}`;
         }

package/src/tools/multi-edit.mjs

@@ -7,6 +7,7 @@
 
 import fs from 'fs';
 import path from 'path';
+import { readStrictUtf8 } from './text-encoding.mjs';
 
 export const MultiEditTool = {
     name: 'MultiEdit',
@@ -57,7 +58,7 @@ export const MultiEditTool = {
 
             if (!fileContents.has(filePath)) {
                 try {
-                    fileContents.set(filePath, fs.readFileSync(filePath, 'utf-8'));
+                    fileContents.set(filePath, readStrictUtf8(filePath));
                 } catch (err) {
                     errors.push(`edit[${i}]: cannot read ${filePath}: ${err.message}`);
                     continue;

package/src/tools/notebook-edit.mjs

@@ -9,6 +9,7 @@
 
 import fs from 'fs';
 import path from 'path';
+import { readStrictUtf8 } from './text-encoding.mjs';
 
 export const NotebookEditTool = {
     name: 'NotebookEdit',
@@ -48,8 +49,9 @@ export const NotebookEditTool = {
         const filePath = path.resolve(input.notebook_path);
 
         try {
-            const raw = fs.readFileSync(filePath, 'utf-8');
-            const notebook = JSON.parse(raw);
+            const raw = readStrictUtf8(filePath);
+            const bom = raw.startsWith('\uFEFF') ? '\uFEFF' : '';
+            const notebook = JSON.parse(bom ? raw.slice(1) : raw);
 
             if (!notebook.cells || !Array.isArray(notebook.cells)) {
                 return 'Error: invalid notebook format (no cells array)';
@@ -87,7 +89,10 @@ export const NotebookEditTool = {
                 }
             }
 
-            fs.writeFileSync(filePath, JSON.stringify(notebook, null, 1));
+            const newline = raw.includes('\r\n') ? '\r\n' : '\n';
+            const trailing = raw.match(/(?:\r?\n)+$/)?.[0] || '';
+            const serialized = JSON.stringify(notebook, null, 1).replace(/\n/g, newline);
+            fs.writeFileSync(filePath, bom + serialized + trailing);
             return `Notebook updated: ${input.operation} at cell ${input.cell_index} (${notebook.cells.length} cells total)`;
         } catch (err) {
             return `Error: ${err.message}`;

package/src/tools/read.mjs

@@ -14,6 +14,29 @@ import path from 'path';
 import { execFileSync } from 'child_process';
 
 const DEFAULT_LIMIT = 2000;
+const MAX_TEXT_BYTES = 16 * 1024 * 1024;
+const MAX_TEXT_LINES = 100000;
+
+// Read a bounded snapshot even if the file grows after the initial stat.
+function readTextSnapshot(filePath) {
+    const fd = fs.openSync(filePath, 'r');
+    try {
+        const size = fs.fstatSync(fd).size;
+        if (size > MAX_TEXT_BYTES) throw new Error('Text file exceeds the 16 MiB hard limit.');
+        const buffer = Buffer.alloc(size + 1);
+        let total = 0;
+        while (total < buffer.length) {
+            const count = fs.readSync(fd, buffer, total, buffer.length - total, total);
+            if (!count) break;
+            total += count;
+        }
+        if (total > size) throw new Error('File changed while reading; retry the read.');
+        if (isBinary(buffer.subarray(0, total))) throw new Error('File appears to be binary. Cannot display binary content.');
+        return buffer.toString('utf-8', 0, total);
+    } finally {
+        fs.closeSync(fd);
+    }
+}
 
 // Track which files have been read (used by Edit and Write tools)
 const readFiles = new Set();
@@ -44,16 +67,24 @@ export const ReadTool = {
             file_path: { type: 'string', description: 'Absolute path to the file' },
             offset: { type: 'number', description: 'Line number to start reading from (0-based)' },
             limit: { type: 'number', description: 'Number of lines to read (default 2000)' },
+            allow_large: { type: 'boolean', description: 'Read beyond the default 2000 lines; explicit offset/limit still apply. Text is capped at 16 MiB and 100000 lines.' },
             pages: { type: 'string', description: 'Page range for PDF files (e.g. "1-5")' },
         },
         required: ['file_path'],
     },
     validateInput(input) {
         const errors = [];
-        if (!input.file_path) errors.push('file_path is required');
+        if (!input || typeof input !== 'object' || Array.isArray(input)) return ['input must be an object'];
+        if (typeof input.file_path !== 'string' || !input.file_path.trim() || input.file_path.includes('\0')) errors.push('file_path must be a nonempty string without null bytes');
+        if (input.offset !== undefined && (!Number.isSafeInteger(input.offset) || input.offset < 0)) errors.push('offset must be a nonnegative safe integer');
+        if (input.limit !== undefined && (!Number.isSafeInteger(input.limit) || input.limit < 1)) errors.push('limit must be a positive safe integer');
+        if (input.allow_large !== undefined && typeof input.allow_large !== 'boolean') errors.push('allow_large must be a boolean');
+        if (input.pages !== undefined && typeof input.pages !== 'string') errors.push('pages must be a string');
         return errors;
     },
     async call(input) {
+        const errors = this.validateInput(input);
+        if (errors.length) return `Error: ${errors.join('; ')}`;
         const filePath = path.resolve(input.file_path);
 
         // Check existence
@@ -72,24 +103,14 @@ export const ReadTool = {
             return readPdf(filePath, input.pages);
         }
 
-        // Binary detection
-        try {
-            const fd = fs.openSync(filePath, 'r');
-            const buf = Buffer.alloc(8192);
-            const bytesRead = fs.readSync(fd, buf, 0, 8192, 0);
-            fs.closeSync(fd);
-            if (isBinary(buf.subarray(0, bytesRead))) {
-                return `Error: ${filePath} appears to be a binary file. Cannot display binary content.`;
-            }
-        } catch (e) {
-            return `Error: ${e.message}`;
-        }
+        if (!stat.isFile()) return 'Error: Read requires a regular file.';
 
         try {
-            const content = fs.readFileSync(filePath, 'utf-8');
+            const content = readTextSnapshot(filePath);
+            if (content.split('\n', MAX_TEXT_LINES + 1).length > MAX_TEXT_LINES) return 'Error: Text file exceeds the 100000 line hard limit.';
             const lines = content.split('\n');
-            const start = input.offset || 0;
-            const limit = input.limit || DEFAULT_LIMIT;
+            const start = input.offset ?? 0;
+            const limit = input.limit ?? (input.allow_large ? MAX_TEXT_LINES : DEFAULT_LIMIT);
             const end = Math.min(start + limit, lines.length);
 
             // Track as read

package/src/tools/registry.mjs

@@ -73,12 +73,12 @@ export function createToolRegistry() {
             }));
         },
 
-        async call(name, input) {
+        async call(name, input, context) {
             const tool = tools.get(name);
             if (!tool) throw new Error(`Unknown tool: ${name}`);
             const errors = tool.validateInput?.(input) || [];
             if (errors.length > 0) return `Validation error: ${errors.join(', ')}`;
-            return tool.call(input);
+            return tool.call(input, context);
         },
 
         register(tool) {

package/src/tools/text-encoding.mjs

@@ -0,0 +1,15 @@
+/**
+ * Decode edit targets without silently replacing malformed byte sequences.
+ * ignoreBOM retains a UTF-8 BOM so ordinary string edits preserve its bytes.
+ */
+import fs from 'node:fs';
+import { TextDecoder } from 'node:util';
+
+export function readStrictUtf8(filePath) {
+    const bytes = fs.readFileSync(filePath);
+    try {
+        return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+    } catch {
+        throw new Error('File is not valid UTF-8. Refusing to edit to avoid corrupting its encoding. Convert it to UTF-8 explicitly first.');
+    }
+}