klyro 0.1.3 → 0.1.5

package/dist/policy/engine.js

@@ -8,6 +8,7 @@
  */
 import { safe } from '../tools/normalize.js';
 export const DEFAULT_POLICY_CONFIG = {
+    mode: 'default',
     shellAllow: [
         'git',
         'ls',
@@ -36,6 +37,10 @@ export const DEFAULT_POLICY_CONFIG = {
         'bcdedit',
     ],
     readSizeAskMiB: 5,
+    allow: [],
+    deny: [],
+    ask: [],
+    additionalDirs: [],
 };
 /**
  * Compose multiple rules. The first rule to return a Decision wins.
@@ -55,6 +60,37 @@ export class PolicyEngine {
             nonInteractive: base.nonInteractive,
             config: this.config,
         };
+        // 3.4 — Permission modes
+        if (ctx.config.mode === 'auto') {
+            // auto / --yolo: allow everything (except hard deny already handled)
+        }
+        else if (ctx.config.mode === 'plan') {
+            // plan mode: block all writes (edit)
+            if (call.name === 'write_file' || call.name === 'edit_file') {
+                return { action: 'deny', reason: 'plan mode: writes blocked — use /permissions to allow or switch mode' };
+            }
+        }
+        else if (ctx.config.mode === 'accept-edits') {
+            // accept-edits: auto-allow edit tools
+            if (call.name === 'write_file' || call.name === 'edit_file') {
+                // fall through to allow, but still check .env below
+            }
+        }
+        // 3.4 — Glob rules allow/deny/ask with precedence deny → allow → ask
+        const globDecision = this.evaluateGlobRules(call);
+        if (globDecision)
+            return globDecision;
+        // 3.4 — .env guard: deny writes to .env files unless explicitly allowed
+        if ((call.name === 'write_file' || call.name === 'edit_file') && typeof call.input.path === 'string') {
+            const p = String(call.input.path);
+            if (/(^|\/)\.env(\.|$)/.test(p) || p.endsWith('.env')) {
+                // Check if explicitly allowed via allow list
+                const allowed = (ctx.config.allow ?? []).some((r) => r.includes('.env'));
+                if (!allowed) {
+                    return { action: 'deny', reason: 'write to .env denied by policy — add to allow list or use --yolo' };
+                }
+            }
+        }
         for (const rule of this.rules) {
             const d = rule.evaluate(call, ctx);
             if (d)
@@ -62,6 +98,24 @@ export class PolicyEngine {
         }
         return { action: 'allow' };
     }
+    evaluateGlobRules(call) {
+        const check = (list, action) => {
+            if (!list || list.length === 0)
+                return null;
+            for (const rule of list) {
+                if (matchesGlobRule(call, rule)) {
+                    if (action === 'allow')
+                        return { action: 'allow' };
+                    if (action === 'deny')
+                        return { action: 'deny', reason: `denied by rule: ${rule}` };
+                    return { action: 'ask', reason: `requires approval per rule: ${rule}` };
+                }
+            }
+            return null;
+        };
+        // Precedence: deny → allow → ask
+        return check(this.config.deny, 'deny') ?? check(this.config.allow, 'allow') ?? check(this.config.ask, 'ask') ?? null;
+    }
 }
 /** Builtin set of rules. Order matters: first match wins. */
 export function builtinRules() {
@@ -75,6 +129,26 @@ export function builtinRules() {
 function asString(v) {
     return typeof v === 'string' ? v : '';
 }
+function matchesGlobRule(call, rule) {
+    // Rule grammar: tool or tool(glob). e.g. "write_file", "write_file(.env)", "shell_exec(npm *)"
+    const m = /^([a-z_]+)(?:\((.*)\))?$/.exec(rule.trim());
+    if (!m)
+        return false;
+    const tool = m[1];
+    const glob = m[2];
+    if (tool !== call.name)
+        return false;
+    if (glob === undefined)
+        return true; // any input for that tool
+    // For shell, match command; for file tools, match path
+    const target = typeof call.input.command === 'string' ? String(call.input.command)
+        : typeof call.input.path === 'string' ? String(call.input.path)
+            : JSON.stringify(call.input);
+    // Simple glob: * matches any, ? matches single, otherwise substring
+    const regexStr = glob.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.');
+    const re = new RegExp(`^${regexStr}$`, 'i');
+    return re.test(target);
+}
 function startsWithAny(haystack, needles) {
     const h = haystack.trim().toLowerCase();
     return needles.some((n) => {
@@ -120,16 +194,25 @@ export const shellAllowRule = {
         return { action: 'ask', reason: `shell command not in allowlist: ${cmd.slice(0, 60)}` };
     },
 };
-/** Writes are auto-allowed if path resolves inside cwd (path-guard throws otherwise). */
+/** Writes are auto-allowed if path resolves inside cwd or --add-dir (path-guard throws otherwise). */
 export const writeFileCwdRule = {
     name: 'write-file-cwd',
-    evaluate(call) {
+    evaluate(call, ctx) {
         if (call.name !== 'write_file' && call.name !== 'edit_file')
             return null;
         const p = asString(call.input.path);
         if (!p)
             return null;
         if (p.includes('..') || path.isAbsolute(p)) {
+            // Check if absolute is inside additionalDirs
+            if (path.isAbsolute(p)) {
+                const allowed = (ctx.config.additionalDirs ?? []).some((dir) => {
+                    const rel = path.relative(path.resolve(dir), path.resolve(p));
+                    return !rel.startsWith('..') && !path.isAbsolute(rel);
+                });
+                if (allowed)
+                    return null;
+            }
             return { action: 'deny', reason: 'path traversal or absolute path not allowed' };
         }
         return null;

package/dist/providers/model-info.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 2.1 — ModelInfo registry: context window, max output, prices, capabilities.
+ */
+export interface ModelInfo {
+    id: string;
+    contextWindow: number;
+    maxOutput: number;
+    inputPricePer1k: number;
+    outputPricePer1k: number;
+    capabilities: {
+        thinking?: boolean;
+        vision?: boolean;
+        tools?: boolean;
+    };
+}
+export declare const MODEL_REGISTRY: Record<string, ModelInfo>;
+export declare function getModelInfo(id: string): ModelInfo;
+export declare function estimateCost(modelId: string, inputTokens: number, outputTokens: number): number;

package/dist/providers/model-info.js

@@ -0,0 +1,18 @@
+/**
+ * 2.1 — ModelInfo registry: context window, max output, prices, capabilities.
+ */
+export const MODEL_REGISTRY = {
+    'claude-3-5-sonnet-20240620': { id: 'claude-3-5-sonnet-20240620', contextWindow: 200000, maxOutput: 8192, inputPricePer1k: 0.003, outputPricePer1k: 0.015, capabilities: { thinking: true, vision: true, tools: true } },
+    'claude-3-haiku-20240307': { id: 'claude-3-haiku-20240307', contextWindow: 200000, maxOutput: 4096, inputPricePer1k: 0.00025, outputPricePer1k: 0.00125, capabilities: { tools: true } },
+    'gpt-4o': { id: 'gpt-4o', contextWindow: 128000, maxOutput: 4096, inputPricePer1k: 0.005, outputPricePer1k: 0.015, capabilities: { vision: true, tools: true } },
+    'gpt-4o-mini': { id: 'gpt-4o-mini', contextWindow: 128000, maxOutput: 4096, inputPricePer1k: 0.00015, outputPricePer1k: 0.0006, capabilities: { tools: true } },
+    'llama3.2': { id: 'llama3.2', contextWindow: 8192, maxOutput: 2048, inputPricePer1k: 0, outputPricePer1k: 0, capabilities: { tools: true } },
+    'local-model': { id: 'local-model', contextWindow: 8192, maxOutput: 2048, inputPricePer1k: 0, outputPricePer1k: 0, capabilities: {} },
+};
+export function getModelInfo(id) {
+    return MODEL_REGISTRY[id] ?? { id, contextWindow: 100000, maxOutput: 4096, inputPricePer1k: 0, outputPricePer1k: 0, capabilities: { tools: true } };
+}
+export function estimateCost(modelId, inputTokens, outputTokens) {
+    const info = getModelInfo(modelId);
+    return (inputTokens / 1000) * info.inputPricePer1k + (outputTokens / 1000) * info.outputPricePer1k;
+}

package/dist/providers.js

@@ -55,9 +55,9 @@ export async function resolveProvider() {
 }
 /** Hit a cheap endpoint to check if a local server is up. */
 async function probeLocal(baseURL) {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), 600);
     try {
-        const ctrl = new AbortController();
-        const t = setTimeout(() => ctrl.abort(), 600);
         // Try the OpenAI-style /models endpoint; some servers (Ollama before load)
         // answer /, others only /v1/models.
         const res = await fetch(`${baseURL.replace(/\/+$/, '')}/models`, {
@@ -68,6 +68,7 @@ async function probeLocal(baseURL) {
         return res.ok;
     }
     catch {
+        clearTimeout(t);
         return false;
     }
 }

package/dist/renderers/json.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 3.1 — JsonRenderer: renders KlyroEvents as JSON lines (machine mode)
+ */
+import type { KlyroEvent } from '../events/catalog.js';
+export declare class JsonRenderer {
+    private out;
+    constructor(out?: NodeJS.WritableStream);
+    handle(ev: KlyroEvent): void;
+}
+export declare class StreamJsonRenderer extends JsonRenderer {
+}

package/dist/renderers/json.js

@@ -0,0 +1,14 @@
+/**
+ * 3.1 — JsonRenderer: renders KlyroEvents as JSON lines (machine mode)
+ */
+export class JsonRenderer {
+    out;
+    constructor(out = process.stdout) {
+        this.out = out;
+    }
+    handle(ev) {
+        this.out.write(JSON.stringify(ev) + '\n');
+    }
+}
+export class StreamJsonRenderer extends JsonRenderer {
+}

package/dist/renderers/terminal.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 3.1 — TerminalRenderer: renders KlyroEvents to terminal (human mode)
+ * No direct writes in core — this is the only place that writes to stdout/stderr for human.
+ */
+import type { KlyroEvent } from '../events/catalog.js';
+export declare class TerminalRenderer {
+    handle(ev: KlyroEvent): void;
+    renderMarkdown(text: string): void;
+}

package/dist/renderers/terminal.js

@@ -0,0 +1,41 @@
+/**
+ * 3.1 — TerminalRenderer: renders KlyroEvents to terminal (human mode)
+ * No direct writes in core — this is the only place that writes to stdout/stderr for human.
+ */
+import { renderMarkdown } from '../cli/markdown.js';
+export class TerminalRenderer {
+    handle(ev) {
+        switch (ev.type) {
+            case 'stream.delta':
+                process.stdout.write(ev.text);
+                break;
+            case 'tool.call':
+                process.stderr.write(`\n[tool] ${ev.name} ${JSON.stringify(ev.input).slice(0, 200)}\n`);
+                break;
+            case 'tool.result':
+                process.stderr.write(`  -> ${ev.isError ? 'ERR' : 'ok'} (${ev.latencyMs}ms)\n`);
+                break;
+            case 'file.changed':
+                process.stderr.write(`  ✎ ${ev.path} (${ev.op})\n`);
+                break;
+            case 'phase.changed':
+                process.stderr.write(`\n[phase] ${ev.phase}\n`);
+                break;
+            case 'verification.started':
+                process.stderr.write(`[verify] ${ev.command}\n`);
+                break;
+            case 'verification.failed':
+                process.stderr.write(`[verify] failed: ${ev.reason.slice(0, 200)}\n`);
+                break;
+            case 'error':
+                process.stderr.write(`✖ ${ev.message}\n`);
+                break;
+            default:
+                break;
+        }
+    }
+    renderMarkdown(text) {
+        const out = renderMarkdown(text, { isTTY: !!process.stdout.isTTY });
+        process.stdout.write(out);
+    }
+}

package/dist/repl.js

@@ -40,8 +40,14 @@ export async function repl(system) {
     // 'SIGINT' event on the interface. Wire it to a clean exit so the user gets
     // exit code 130 (the conventional 128+SIGINT(2)) instead of a crash.
     rl.on('SIGINT', () => {
-        process.stdout.write('\n');
-        rl.close();
+        try {
+            process.stdout.write('\n');
+        }
+        catch { /* ignore */ }
+        try {
+            rl.close();
+        }
+        catch { /* ignore */ }
         exit(130);
     });
     if (isTTY)
@@ -87,19 +93,34 @@ export async function repl(system) {
         rl.close();
     }
 }
-/** Drop oldest turns to stay under the size cap. */
+/** Drop oldest turns to stay under the size cap. Keep user/assistant pairs together. */
 function trimHistory(history) {
-    while (history.length > MAX_HISTORY_TURNS)
-        history.shift();
+    // Keep even number of turns (pairs) when trimming for turn count
+    while (history.length > MAX_HISTORY_TURNS) {
+        // Drop oldest 2 (user+assistant) to preserve adjacency
+        if (history.length >= 2) {
+            history.shift();
+            history.shift();
+        }
+        else {
+            history.shift();
+        }
+    }
     let total = 0;
     for (const t of history)
         total += t.content.length;
     while (total > MAX_HISTORY_CHARS && history.length > 2) {
-        const head = history[0];
-        if (!head)
+        // Drop oldest pair to avoid orphaning tool context
+        const first = history[0];
+        const second = history[1];
+        if (!first)
             break;
-        total -= head.content.length;
+        total -= first.content.length;
         history.shift();
+        if (second) {
+            total -= second.content.length;
+            history.shift();
+        }
     }
 }
 /** Send the full history, stream the reply, return the assistant text. */
@@ -146,14 +167,27 @@ async function ask(baseURL, apiKey, model, system, history) {
         return '';
     }
     // Use the shared streamToStdout from chat.ts. Capture what we wrote so we
-    // can return it for the conversation history.
+    // can return it for the conversation history. Handle Buffer/Uint8Array and re-entrancy.
     const collected = [];
     const origWrite = process.stdout.write.bind(process.stdout);
-    process.stdout.write = (chunk) => {
-        if (typeof chunk === 'string')
-            collected.push(chunk);
-        return origWrite(chunk);
-    };
+    const alreadyWrapped = !!process.stdout.write.__klyroWrapped;
+    let didWrap = false;
+    if (!alreadyWrapped) {
+        const wrapped = function (chunk, encoding, cb) {
+            if (typeof chunk === 'string')
+                collected.push(chunk);
+            else if (chunk instanceof Buffer)
+                collected.push(chunk.toString('utf-8'));
+            else if (chunk instanceof Uint8Array)
+                collected.push(Buffer.from(chunk).toString('utf-8'));
+            else if (chunk != null)
+                collected.push(String(chunk));
+            return origWrite(chunk, encoding, cb);
+        };
+        wrapped.__klyroWrapped = true;
+        process.stdout.write = wrapped;
+        didWrap = true;
+    }
     try {
         await streamToStdout(res.body, ac.signal);
     }
@@ -164,7 +198,10 @@ async function ask(baseURL, apiKey, model, system, history) {
         }
     }
     finally {
-        process.stdout.write = origWrite;
+        if (didWrap) {
+            process.stdout.write = origWrite;
+        }
     }
+    // If we were already wrapped (re-entrant), outer wrapper already captured, so return whatever we collected (may be empty)
     return collected.join('');
 }

package/dist/shared/errors.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared KlyroError — base for all harness errors.
+ * Carries code, hint, exitCode, retryable for CLI mapping.
+ */
+export type KlyroErrorCode = 'CONFIG_INVALID' | 'CONFIG_NOT_FOUND' | 'PROVIDER_AUTH' | 'PROVIDER_RATE_LIMIT' | 'PROVIDER_TIMEOUT' | 'TOOL_DENIED' | 'TOOL_NOT_FOUND' | 'PATH_ESCAPE' | 'VERIFY_FAILED' | 'PERSIST_ERROR' | 'UNKNOWN';
+export declare const EXIT_CODE: Record<KlyroErrorCode, number>;
+export declare class KlyroError extends Error {
+    readonly code: KlyroErrorCode;
+    readonly hint?: string;
+    readonly exitCode: number;
+    readonly retryable: boolean;
+    constructor(code: KlyroErrorCode, message: string, opts?: {
+        hint?: string;
+        exitCode?: number;
+        retryable?: boolean;
+        cause?: unknown;
+    });
+}

package/dist/shared/errors.js

@@ -0,0 +1,33 @@
+/**
+ * Shared KlyroError — base for all harness errors.
+ * Carries code, hint, exitCode, retryable for CLI mapping.
+ */
+export const EXIT_CODE = {
+    CONFIG_INVALID: 3,
+    CONFIG_NOT_FOUND: 3,
+    PROVIDER_AUTH: 4,
+    PROVIDER_RATE_LIMIT: 4,
+    PROVIDER_TIMEOUT: 4,
+    TOOL_DENIED: 2,
+    TOOL_NOT_FOUND: 2,
+    PATH_ESCAPE: 2,
+    VERIFY_FAILED: 8,
+    PERSIST_ERROR: 2,
+    UNKNOWN: 1,
+};
+export class KlyroError extends Error {
+    code;
+    hint;
+    exitCode;
+    retryable;
+    constructor(code, message, opts = {}) {
+        super(message);
+        this.name = 'KlyroError';
+        this.code = code;
+        this.hint = opts.hint;
+        this.exitCode = opts.exitCode ?? EXIT_CODE[code] ?? 1;
+        this.retryable = opts.retryable ?? false;
+        if (opts.cause)
+            this.cause = opts.cause;
+    }
+}

package/dist/shared/index.d.ts

@@ -0,0 +1,2 @@
+export * from './errors.js';
+export * from './types.js';

package/dist/shared/index.js

@@ -0,0 +1,2 @@
+export * from './errors.js';
+export * from './types.js';

package/dist/shared/types.d.ts

@@ -0,0 +1,19 @@
+/** Base types shared across CLI, core, providers. */
+export type Role = 'user' | 'assistant' | 'tool' | 'system';
+export interface ContentBlock {
+    kind: 'text' | 'image' | 'tool_use' | 'tool_result' | 'thinking';
+    text?: string;
+    imageUrl?: string;
+    id?: string;
+    name?: string;
+    input?: unknown;
+    toolCallId?: string;
+    output?: unknown;
+    isError?: boolean;
+}
+export interface Message {
+    role: Role;
+    content: ContentBlock[];
+}
+export type ExitCode = 0 | 1 | 2 | 3 | 4 | 7 | 8 | 130;
+export declare const EXIT_TABLE: Record<string, number>;

package/dist/shared/types.js

@@ -0,0 +1,11 @@
+/** Base types shared across CLI, core, providers. */
+export const EXIT_TABLE = {
+    success: 0,
+    error: 1,
+    usage: 2,
+    config: 3,
+    provider: 4,
+    limit: 7,
+    verify: 8,
+    aborted: 130,
+};

package/dist/tools/fs/read-file.d.ts

@@ -31,36 +31,6 @@ export declare const readFileTool: import("../types.js").Tool<{
     startLine?: number | undefined;
     endLine?: number | undefined;
     maxBytes?: number | undefined;
-}, {
-    readonly ok: false;
-    readonly error: {
-        readonly code: "INVALID_INPUT";
-        readonly message: `Not a regular file: ${string}`;
-    };
-    path?: undefined;
-    totalLines?: undefined;
-    lines?: undefined;
-    bytesRead?: undefined;
-    truncated?: undefined;
-} | {
-    readonly ok: false;
-    readonly error: {
-        readonly code: "INVALID_INPUT";
-        readonly message: `File too large (${number} bytes). Use startLine/endLine or raise maxBytes.`;
-    };
-    path?: undefined;
-    totalLines?: undefined;
-    lines?: undefined;
-    bytesRead?: undefined;
-    truncated?: undefined;
-} | {
-    path: string;
-    totalLines: number;
-    lines: string[];
-    bytesRead: number;
-    truncated: boolean;
-    readonly ok?: undefined;
-    readonly error?: undefined;
-}>;
+}, ReadFileOutput>;
 export type ReadFileInput = z.infer<typeof InputSchema>;
 export {};

package/dist/tools/fs/read-file.js

@@ -17,6 +17,7 @@ import { z } from 'zod';
 import { defineTool } from '../types.js';
 import { resolveAndFollowSymlinks } from '../../policy/path-guard.js';
 import { TOOL_ERROR_CODES, safe } from '../normalize.js';
+import { markRead } from './read-history.js';
 const InputSchema = z.object({
     path: z.string().min(1).describe('Path relative to cwd, or absolute path inside cwd'),
     startLine: z.number().int().min(1).optional().describe('1-indexed inclusive start line'),
@@ -28,44 +29,71 @@ export const readFileTool = defineTool({
     name: 'read_file',
     description: 'Read a file from the workspace. Returns the lines and total line count. Use startLine/endLine to read a slice without pulling the whole file.',
     inputSchema: InputSchema,
+    permission: 'read',
+    isConcurrencySafe: true,
+    renderCall: (input) => `read_file ${input.path}${input.startLine ? `:${input.startLine}-${input.endLine ?? ''}` : ''}`,
+    renderResult: (output) => `${output.path} (${output.totalLines} lines, ${output.bytesRead} bytes${output.truncated ? ' truncated' : ''})`,
     execute: async (input, ctx) => {
         return safe(async () => {
             const { resolved } = await resolveAndFollowSymlinks(ctx.cwd, input.path);
             const maxBytes = input.maxBytes ?? DEFAULT_MAX_BYTES;
             const stat = await fs.stat(resolved);
             if (!stat.isFile()) {
-                return {
-                    ok: false,
-                    error: { code: TOOL_ERROR_CODES.INVALID_INPUT, message: `Not a regular file: ${input.path}` },
-                };
+                throw Object.assign(new Error(`Not a regular file: ${input.path}`), { code: TOOL_ERROR_CODES.INVALID_INPUT });
+            }
+            // >10MB refusal per 3.2 spec
+            if (stat.size > 10 * 1024 * 1024) {
+                throw Object.assign(new Error(`File too large (${stat.size} bytes) — >10MB refusal. Use startLine/endLine to read a slice.`), { code: TOOL_ERROR_CODES.INVALID_INPUT });
             }
             if (stat.size > maxBytes * 4 && !input.startLine && !input.endLine) {
-                return {
-                    ok: false,
-                    error: {
-                        code: TOOL_ERROR_CODES.INVALID_INPUT,
-                        message: `File too large (${stat.size} bytes). Use startLine/endLine or raise maxBytes.`,
-                    },
-                };
+                throw Object.assign(new Error(`File too large (${stat.size} bytes). Use startLine/endLine or raise maxBytes.`), { code: TOOL_ERROR_CODES.INVALID_INPUT });
             }
             const fh = await fs.open(resolved, 'r');
             try {
                 const buf = Buffer.alloc(Math.min(maxBytes, stat.size));
                 const { bytesRead } = await fh.read(buf, 0, buf.length, 0);
+                // Binary detection: null byte or high binary ratio
+                if (buf.subarray(0, bytesRead).includes(0)) {
+                    throw Object.assign(new Error(`Binary file: ${input.path} (contains null byte). Use image handling or cat -n for text.`), { code: TOOL_ERROR_CODES.INVALID_INPUT });
+                }
                 const text = new TextDecoder('utf-8').decode(buf.subarray(0, bytesRead));
                 const allLines = text.split(/\r\n|\r|\n/);
                 const truncated = bytesRead < stat.size;
                 const totalLines = truncated ? -1 : allLines.length;
-                const lines = input.startLine !== undefined || input.endLine !== undefined
-                    ? allLines.slice((input.startLine ?? 1) - 1, input.endLine ?? allLines.length)
-                    : allLines;
-                return {
+                // 2000-line window per spec (cap)
+                const windowSize = 2000;
+                let lines;
+                if (input.startLine !== undefined || input.endLine !== undefined) {
+                    const s = (input.startLine ?? 1) - 1;
+                    const e = input.endLine ?? Math.min(allLines.length, s + windowSize);
+                    lines = allLines.slice(s, Math.min(e, s + windowSize));
+                }
+                else {
+                    lines = allLines.slice(0, Math.min(allLines.length, windowSize));
+                }
+                // Truncation to 8k tokens equivalent ~32k chars
+                const maxChars = 32_000;
+                let outLines = lines;
+                let truncatedTokens = false;
+                const asText = lines.join('\n');
+                if (asText.length > maxChars) {
+                    outLines = asText.slice(0, maxChars).split('\n');
+                    truncatedTokens = true;
+                }
+                // cat -n style: prefix line numbers for model readability (when returning)
+                // We keep raw lines but add hint in truncated case
+                const result = {
                     path: input.path,
                     totalLines,
-                    lines,
+                    lines: outLines,
                     bytesRead,
-                    truncated,
+                    truncated: truncated || truncatedTokens,
                 };
+                if (truncatedTokens) {
+                    result.hint = 'Truncated to 8k tokens — use startLine/endLine to get more';
+                }
+                markRead(input.path);
+                return result;
             }
             finally {
                 await fh.close().catch(() => undefined);

package/dist/tools/fs/read-history.d.ts

@@ -0,0 +1,3 @@
+export declare function markRead(p: string): void;
+export declare function wasRead(p: string): boolean;
+export declare function clearReadHistory(): void;

package/dist/tools/fs/read-history.js

@@ -0,0 +1,13 @@
+/** Track files read this session for write guard (3.2) */
+const sessionReadFiles = new Set();
+export function markRead(p) {
+    sessionReadFiles.add(p);
+    // Also add normalized
+    sessionReadFiles.add(p.replace(/\\/g, '/'));
+}
+export function wasRead(p) {
+    return sessionReadFiles.has(p) || sessionReadFiles.has(p.replace(/\\/g, '/'));
+}
+export function clearReadHistory() {
+    sessionReadFiles.clear();
+}

package/dist/tools/fs/write-file.d.ts

@@ -16,9 +16,6 @@ export interface WriteFileOutput {
 export declare const writeFileTool: import("../types.js").Tool<{
     path: string;
     content: string;
-}, {
-    path: string;
-    bytesWritten: number;
-}>;
+}, WriteFileOutput>;
 export type WriteFileInput = z.infer<typeof InputSchema>;
 export {};