atom-agent 1.1.0 → 1.2.0

package/dist/sessions.js

@@ -0,0 +1,524 @@
+// Durable multi-session store for ATOM.
+//
+// One JSON file per session under ~/.atom/sessions/<id>.json (ATOM_HOME
+// override honored via auth.ts's atomDir) plus a plaintext pointer file
+// ~/.atom/sessions/active holding the active session id.
+//
+// This module never touches the legacy single-file save owned by
+// src/session.ts (~/.atom/session.json) — that file stays exactly as-is.
+//
+// Conventions (mirroring session.ts / auth.ts):
+// - Writes are atomic (temp file + rename, mkdir -p) so a kill mid-write
+//   can never leave a half-written record; no .tmp leftovers on failure.
+// - 0600 POSIX perms, best-effort on Windows (never throws for chmod).
+// - Loads never throw: missing -> null, malformed -> null, and listings
+//   silently skip corrupt files.
+// - provider/model/effort/mode are opaque carried fields. The literal
+//   defaults below are documented here on purpose — this module must NOT
+//   depend on DEFAULT_PROVIDER from zen.js (avoid coupling) and must NEVER
+//   import LLM clients.
+// - No transient UI state (scroll, cursor, picker, queue) is stored.
+//
+// Import budget: value imports are node:fs, node:path, node:crypto and
+// ./auth.js only (type-only imports from ./zen.js / ./providers.js are
+// erased at compile, so the runtime DAG stays acyclic and React-free).
+import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { randomUUID } from "node:crypto";
+import * as path from "node:path";
+import { atomDir } from "./auth.js";
+// Literal defaults for new sessions (opaque carried fields — see header).
+export const SESSION_DEFAULT_PROVIDER = "opencode-zen";
+export const SESSION_DEFAULT_MODEL = "";
+export const SESSION_DEFAULT_EFFORT = "default";
+export const SESSION_DEFAULT_MODE = "normal";
+export const SESSIONS_DIRNAME = "sessions";
+export const ACTIVE_FILENAME = "active";
+export function sessionsDir(home) {
+    return path.join(atomDir(home), SESSIONS_DIRNAME);
+}
+export function sessionFilePath(id, home) {
+    return path.join(sessionsDir(home), `${id}.json`);
+}
+export function activeFilePath(home) {
+    return path.join(sessionsDir(home), ACTIVE_FILENAME);
+}
+const MONTHS = [
+    "January",
+    "February",
+    "March",
+    "April",
+    "May",
+    "June",
+    "July",
+    "August",
+    "September",
+    "October",
+    "November",
+    "December",
+];
+// Default display title: local date+time like "September 9, 2026 20:41:32"
+// (long English month, unpadded day, 24h zero-padded HH:MM:SS local time).
+// createdAt stays a separate ISO string on the record.
+export function formatSessionTitle(date = new Date()) {
+    const d = date instanceof Date && !Number.isNaN(date.getTime()) ? date : new Date();
+    const pad = (n) => String(n).padStart(2, "0");
+    return (`${MONTHS[d.getMonth()]} ${d.getDate()}, ${d.getFullYear()} ` +
+        `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`);
+}
+function newSessionId() {
+    return `ses_${randomUUID().replace(/-/g, "")}`;
+}
+function toISODate(now) {
+    if (now === undefined)
+        return new Date().toISOString();
+    const d = now instanceof Date ? now : new Date(now);
+    return Number.isNaN(d.getTime()) ? new Date().toISOString() : d.toISOString();
+}
+function safeCwd() {
+    try {
+        return process.cwd();
+    }
+    catch {
+        return "";
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function isValidDateString(value) {
+    return (typeof value === "string" &&
+        value.length > 0 &&
+        !Number.isNaN(Date.parse(value)));
+}
+// Atomic write: temp file + rename, 0600 POSIX best-effort. Cleans up the
+// temp file when the write/rename fails so no .tmp leftovers remain. Disk
+// errors propagate to the caller.
+function writeFileAtomic(finalPath, content) {
+    mkdirSync(path.dirname(finalPath), { recursive: true });
+    const tmpPath = `${finalPath}.tmp.${process.pid}`;
+    try {
+        writeFileSync(tmpPath, content, "utf8");
+        try {
+            chmodSync(tmpPath, 0o600);
+        }
+        catch {
+            // best-effort on Windows; ignore
+        }
+        renameSync(tmpPath, finalPath);
+    }
+    catch (err) {
+        try {
+            if (existsSync(tmpPath))
+                unlinkSync(tmpPath);
+        }
+        catch {
+            // cleanup best-effort; report the original failure
+        }
+        throw err;
+    }
+}
+function validateUsageTotals(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (!isRecord(value))
+        return null;
+    const out = {};
+    for (const key of [
+        "prompt_tokens",
+        "completion_tokens",
+        "total_tokens",
+        "cacheReadTokens",
+        "cacheWriteTokens",
+    ]) {
+        const v = value[key];
+        if (typeof v === "number" && Number.isFinite(v) && v >= 0) {
+            out[key] = Math.floor(v);
+        }
+    }
+    return out;
+}
+function validateToolCall(value) {
+    if (!isRecord(value))
+        return false;
+    if (!isNonEmptyString(value["id"]))
+        return false;
+    const fn = value["function"];
+    if (!isRecord(fn))
+        return false;
+    if (typeof fn["name"] !== "string" || fn["name"].length === 0)
+        return false;
+    if (typeof fn["arguments"] !== "string")
+        return false;
+    if (value["type"] !== undefined && typeof value["type"] !== "string") {
+        return false;
+    }
+    return true;
+}
+function validateChatMessage(value) {
+    if (!isRecord(value))
+        return false;
+    const role = value["role"];
+    if (role === "system" || role === "user") {
+        return typeof value["content"] === "string";
+    }
+    if (role === "assistant") {
+        const content = value["content"];
+        if (content !== undefined &&
+            content !== null &&
+            typeof content !== "string") {
+            return false;
+        }
+        const calls = value["tool_calls"];
+        if (calls !== undefined) {
+            if (!Array.isArray(calls) || calls.length === 0)
+                return false;
+            for (const c of calls) {
+                if (!validateToolCall(c))
+                    return false;
+            }
+        }
+        return true;
+    }
+    if (role === "tool") {
+        return (isNonEmptyString(value["tool_call_id"]) &&
+            typeof value["content"] === "string");
+    }
+    return false;
+}
+function validateTurn(value) {
+    if (!isRecord(value))
+        return false;
+    const role = value["role"];
+    if (role !== "user" && role !== "assistant" && role !== "tool")
+        return false;
+    if (typeof value["content"] !== "string")
+        return false;
+    if (value["error"] !== undefined && typeof value["error"] !== "boolean") {
+        return false;
+    }
+    if (value["thinking"] !== undefined &&
+        typeof value["thinking"] !== "boolean") {
+        return false;
+    }
+    return true;
+}
+// Strict-enough read validation: bad shape -> null (caller treats the file
+// as missing/corrupt, never throws). Unknown extra keys are ignored.
+// provider/model/effort/mode stay opaque (typeof string only — any id,
+// including "", round-trips) so this store never couples to LLM clients.
+function validateSessionRecord(data) {
+    if (!isRecord(data))
+        return null;
+    if (!isNonEmptyString(data["id"]))
+        return null;
+    if (typeof data["title"] !== "string" || data["title"].trim().length === 0) {
+        return null;
+    }
+    if (!isValidDateString(data["createdAt"]))
+        return null;
+    if (!isValidDateString(data["updatedAt"]))
+        return null;
+    if (typeof data["cwd"] !== "string")
+        return null;
+    if (typeof data["provider"] !== "string")
+        return null;
+    if (typeof data["model"] !== "string")
+        return null;
+    if (typeof data["effort"] !== "string")
+        return null;
+    if (typeof data["mode"] !== "string")
+        return null;
+    const history = data["history"];
+    if (!Array.isArray(history))
+        return null;
+    for (const m of history) {
+        if (!validateChatMessage(m))
+            return null;
+    }
+    const turns = data["turns"];
+    if (!Array.isArray(turns))
+        return null;
+    for (const t of turns) {
+        if (!validateTurn(t))
+            return null;
+    }
+    const metadata = data["metadata"];
+    return {
+        id: data["id"],
+        title: data["title"],
+        createdAt: data["createdAt"],
+        updatedAt: data["updatedAt"],
+        cwd: data["cwd"],
+        provider: data["provider"],
+        model: data["model"],
+        effort: data["effort"],
+        mode: data["mode"],
+        usageTotals: validateUsageTotals(data["usageTotals"]),
+        history: history,
+        turns: turns,
+        metadata: isRecord(metadata) ? { ...metadata } : {},
+    };
+}
+function readSessionFile(filePath) {
+    let raw;
+    try {
+        if (!existsSync(filePath))
+            return null;
+        raw = readFileSync(filePath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    return validateSessionRecord(data);
+}
+function persistSession(session, home) {
+    writeFileAtomic(sessionFilePath(session.id, home), JSON.stringify(session, null, 2) + "\n");
+}
+export function createSession(opts = {}, home) {
+    const at = toISODate(opts.now);
+    let id = typeof opts.id === "string" && opts.id.length > 0 ? opts.id : newSessionId();
+    // Never silently overwrite: an explicit id that already exists (caller
+    // retry / collision) falls back to a fresh id, so ids stay unique. The
+    // check-then-write races only across processes (last-writer-wins, the
+    // documented store posture); each write itself stays atomic.
+    if (id === opts.id && opts.id) {
+        let exists = false;
+        try {
+            exists = existsSync(sessionFilePath(id, home));
+        }
+        catch {
+            exists = false;
+        }
+        if (exists)
+            id = newSessionId();
+    }
+    const rawTitle = typeof opts.title === "string" ? opts.title.trim() : "";
+    const session = {
+        id,
+        title: rawTitle.length > 0 ? rawTitle : formatSessionTitle(new Date(at)),
+        createdAt: at,
+        updatedAt: at,
+        cwd: typeof opts.cwd === "string" ? opts.cwd : safeCwd(),
+        provider: opts.provider ?? SESSION_DEFAULT_PROVIDER,
+        model: opts.model ?? SESSION_DEFAULT_MODEL,
+        effort: opts.effort ?? SESSION_DEFAULT_EFFORT,
+        mode: opts.mode ?? SESSION_DEFAULT_MODE,
+        usageTotals: opts.usageTotals === undefined || opts.usageTotals === null
+            ? null
+            : validateUsageTotals(opts.usageTotals),
+        history: (opts.history ?? []).map((m) => ({ ...m })),
+        turns: (opts.turns ?? []).map((t) => ({ ...t })),
+        metadata: isRecord(opts.metadata) ? { ...opts.metadata } : {},
+    };
+    persistSession(session, home);
+    // First session wins the active pointer; later creates leave it alone.
+    if (getActiveSessionId(home) === null) {
+        setActiveSession(session.id, home);
+    }
+    return session;
+}
+export function getSession(id, home) {
+    if (typeof id !== "string" || id.length === 0)
+        return null;
+    return readSessionFile(sessionFilePath(id, home));
+}
+// Alias-safe full-record read.
+export function loadSession(id, home) {
+    return getSession(id, home);
+}
+export function listSessions(home) {
+    let entries;
+    try {
+        entries = readdirSync(sessionsDir(home));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const entry of entries) {
+        if (!entry.endsWith(".json"))
+            continue;
+        const session = readSessionFile(path.join(sessionsDir(home), entry));
+        if (session)
+            out.push(session);
+    }
+    out.sort((a, b) => {
+        const updated = Date.parse(b.updatedAt) - Date.parse(a.updatedAt);
+        if (updated !== 0)
+            return updated;
+        const created = Date.parse(b.createdAt) - Date.parse(a.createdAt);
+        if (created !== 0)
+            return created;
+        return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+    });
+    return out;
+}
+export function updateSession(id, patch, home) {
+    const current = getSession(id, home);
+    if (!current || !isRecord(patch))
+        return null;
+    const { id: _droppedId, createdAt: _droppedCreatedAt, ...rest } = patch;
+    void _droppedId;
+    void _droppedCreatedAt;
+    const candidate = {
+        ...current,
+        ...rest,
+        id: current.id,
+        createdAt: current.createdAt,
+        updatedAt: typeof rest["updatedAt"] === "string" &&
+            isValidDateString(rest["updatedAt"])
+            ? rest["updatedAt"]
+            : new Date().toISOString(),
+    };
+    if (typeof candidate["title"] === "string") {
+        candidate["title"] = candidate["title"].trim();
+    }
+    if (Array.isArray(candidate["history"])) {
+        candidate["history"] = candidate["history"].map((m) => isRecord(m) ? { ...m } : m);
+    }
+    if (Array.isArray(candidate["turns"])) {
+        candidate["turns"] = candidate["turns"].map((t) => isRecord(t) ? { ...t } : t);
+    }
+    if (candidate["metadata"] !== undefined &&
+        !isRecord(candidate["metadata"])) {
+        return null;
+    }
+    const valid = validateSessionRecord(candidate);
+    if (!valid)
+        return null;
+    persistSession(valid, home);
+    return valid;
+}
+export function renameSession(id, title, home) {
+    if (typeof title !== "string" || title.trim().length === 0)
+        return null;
+    const current = getSession(id, home);
+    if (!current)
+        return null;
+    const next = {
+        ...current,
+        title: title.trim(),
+        updatedAt: new Date().toISOString(),
+    };
+    persistSession(next, home);
+    return next;
+}
+export function deleteSession(id, home) {
+    if (typeof id !== "string" || id.length === 0)
+        return false;
+    const filePath = sessionFilePath(id, home);
+    try {
+        if (!existsSync(filePath))
+            return false;
+        unlinkSync(filePath);
+    }
+    catch {
+        return false;
+    }
+    // Clear the active pointer only when it pointed at the deleted session.
+    try {
+        if (getActiveSessionId(home) === id)
+            setActiveSession(null, home);
+    }
+    catch {
+        // never throws; active cleanup is best-effort
+    }
+    return true;
+}
+// Full-record overwrite. The stored id/createdAt win when a record already
+// exists on disk — id/createdAt can never be mutated through save.
+// updatedAt always bumps to now.
+export function saveSession(session, home) {
+    if (!session || !isNonEmptyString(session.id)) {
+        throw new Error("saveSession: session.id must be a non-empty string");
+    }
+    const disk = getSession(session.id, home);
+    const candidate = {
+        ...session,
+        id: disk ? disk.id : session.id,
+        createdAt: disk ? disk.createdAt : session.createdAt,
+        updatedAt: new Date().toISOString(),
+    };
+    const valid = validateSessionRecord(candidate);
+    if (!valid) {
+        throw new Error("saveSession: session record failed validation");
+    }
+    persistSession(valid, home);
+    return valid;
+}
+// Bump updatedAt to now (runtime message/assistant/tool mutations). The
+// caller mutates content via updateSession/saveSession; touch only refreshes
+// the recency marker so listings sort correctly.
+export function touchSession(id, home) {
+    const current = getSession(id, home);
+    if (!current)
+        return null;
+    const next = { ...current, updatedAt: new Date().toISOString() };
+    persistSession(next, home);
+    return next;
+}
+// null clears the pointer. Unknown ids are ignored (active unchanged).
+// Never throws.
+export function setActiveSession(id, home) {
+    try {
+        const activePath = activeFilePath(home);
+        if (id === null) {
+            try {
+                if (existsSync(activePath))
+                    unlinkSync(activePath);
+            }
+            catch {
+                // best-effort clear; ignore
+            }
+            return;
+        }
+        if (typeof id !== "string" || id.length === 0)
+            return;
+        if (!getSession(id, home))
+            return;
+        writeFileAtomic(activePath, id);
+    }
+    catch {
+        // never throws; ignore
+    }
+}
+export function getActiveSessionId(home) {
+    try {
+        const activePath = activeFilePath(home);
+        if (!existsSync(activePath))
+            return null;
+        const raw = readFileSync(activePath, "utf8").trim();
+        return raw.length > 0 ? raw : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function getActiveSession(home) {
+    const id = getActiveSessionId(home);
+    if (!id)
+        return null;
+    return getSession(id, home);
+}
+// Return the active session when it still exists on disk, else create (and
+// activate, when nothing is set) a new one from opts.
+export function ensureActiveSession(opts = {}, home) {
+    const active = getActiveSession(home);
+    if (active)
+        return active;
+    const created = createSession(opts, home);
+    // createSession only claims the pointer when none is set; a dangling
+    // pointer must be re-pointed at the replacement session.
+    setActiveSession(created.id, home);
+    return created;
+}

package/dist/system.js

@@ -13,17 +13,93 @@
 // arrive as `Error: ...` text inside the result (invalid args say how to
 // fix; a denial means replan, never retry).
 export const SYSTEM_PROMPT = [
-    "You are ATOM, a long-horizon coding agent that works through tools.",
-    "",
-    "Loop every task: explore, plan, implement, verify, report.",
-    "Plan 3+ step tasks with todowrite: full list up front, exactly one in_progress, mark completed immediately, never batch.",
-    "Read files before editing them. Search existing code before writing new code. Match surrounding patterns.",
-    "Prefer the smallest correct change. Fix root causes. Handle errors and edge cases. Remove dead code.",
-    "Ground every claim in tool output, never in memory. Run commands to check facts.",
-    "After each tool result, reflect briefly, then take the best next action toward the goal.",
-    "Batch independent work in one block: parallel-safe reads and searches in the same response run concurrently and finish in a single round-trip — one call per response is the slow path.",
-    "Keep calling tools until verified done. Never end on an unverified summary or a guess.",
-    "Done means tests and typecheck pass, or the blocker is named with its evidence.",
-    "",
-    "Harness contract: tools never throw — results are strings, failures arrive as `Error: ...` text. Read the error and adapt: invalid args say how to fix, a denial means replan around it, never retry it.",
+    "You are ATOM, an autonomous AI coding agent created by beast-ofcourse (Bhavin).",
+    "Your job is to solve software-engineering tasks accurately, efficiently, and with minimal unnecessary changes.",
+    "",
+    "## Core Loop",
+    "For every task, continuously follow:",
+    "UNDERSTAND → EXPLORE → PLAN → EXECUTE → VERIFY → COMPLETE",
+    "",
+    "Do not stop merely because the code was changed. A task is complete only when the result has been verified or a concrete blocker has been established with evidence.",
+    "",
+    "## Understand",
+    "- Identify the user's actual goal, constraints, and acceptance criteria.",
+    "- Resolve ambiguity from the repository before asking questions when the answer can be discovered with tools.",
+    "- Do not assume repository structure, APIs, behavior, or configuration. Inspect them.",
+    "",
+    "## Explore",
+    "- Read relevant files before modifying them.",
+    "- Search the repository before creating new code.",
+    "- Trace existing implementations, call sites, types, configuration, and tests.",
+    "- Prefer understanding existing architecture over introducing parallel implementations.",
+    "- For unfamiliar code, inspect enough surrounding context to understand how it actually works.",
+    "",
+    "## Plan",
+    "- For non-trivial tasks, create a concise ordered todo list before implementation.",
+    "- Keep exactly one todo in progress at a time.",
+    "- Mark todos complete immediately after their work is actually finished.",
+    "- Adapt the plan when exploration or verification reveals new information.",
+    "- Do not create unnecessary work just to satisfy the plan.",
+    "",
+    "## Execute",
+    "- Make the smallest correct change that solves the underlying problem.",
+    "- Preserve existing architecture, conventions, APIs, and behavior unless the task requires changing them.",
+    "- Reuse existing utilities, abstractions, and patterns before introducing new ones.",
+    "- Fix root causes rather than symptoms.",
+    "- Handle relevant errors, edge cases, race conditions, and failure paths.",
+    "- Avoid speculative features, unnecessary refactors, and unrelated formatting changes.",
+    "- Remove dead code or obsolete logic when your change makes it unnecessary.",
+    "",
+    "## Tool Strategy",
+    "- Tools are your source of truth for the repository and environment.",
+    "- Never claim something is true when it has not been established by tool output.",
+    "- Batch independent reads, searches, inspections, and other safe operations whenever possible.",
+    "- Prefer parallel tool execution over sequential calls when operations have no dependencies.",
+    "- Do not parallelize operations that depend on each other's results or could conflict.",
+    "- After each tool result, determine what information it provides, what remains unknown, and what action has the highest value next.",
+    "- Avoid repeatedly reading the same information unless the repository changed or verification requires it.",
+    "",
+    "## Verification",
+    "- Verify behavior after implementation.",
+    "- Run the most relevant tests, typechecks, linters, builds, or targeted checks available.",
+    "- Prefer targeted verification first, then broader verification when appropriate.",
+    "- Inspect failures instead of blindly retrying.",
+    "- If a test, command, or check fails because of your change, fix it before declaring completion.",
+    "- Do not declare success based solely on compilation if runtime behavior remains unverified.",
+    "- Do not end with an unverified summary.",
+    "",
+    "## Failure Recovery",
+    "- Tool failures are information, not reasons to stop.",
+    "- Tools return failures as text such as `Error: ...`; read the error carefully and adapt.",
+    "- Invalid arguments: correct the arguments using the tool's feedback.",
+    "- Permission or capability denial: replan using an available approach.",
+    "- Environment failure: determine whether the failure is caused by ATOM, the repository, or the environment.",
+    "- Never repeat the same failed action without changing the underlying cause.",
+    "- If progress is impossible, report the exact blocker and the evidence that proves it.",
+    "",
+    "## Efficiency",
+    "- Minimize unnecessary tool calls, context usage, latency, and duplicated work.",
+    "- Prefer high-information actions that answer multiple questions at once.",
+    "- Use repository search and targeted inspection instead of reading large unrelated files.",
+    "- Keep tool chains moving: when one result enables several independent next actions, perform them together.",
+    "- Do not waste time narrating internal reasoning to the user.",
+    "",
+    "## Code Quality",
+    "- Favor simple, readable, maintainable code.",
+    "- Follow the repository's existing style rather than imposing a personal style.",
+    "- Keep abstractions proportional to the problem.",
+    "- Avoid duplicated logic.",
+    "- Keep types accurate and explicit where they improve correctness.",
+    "- Preserve backwards compatibility unless breaking behavior is explicitly required.",
+    "- Consider security, performance, concurrency, resource cleanup, and error handling when relevant.",
+    "",
+    "## Completion Contract",
+    "Before finishing, confirm:",
+    "1. The requested behavior was implemented.",
+    "2. Relevant existing behavior was preserved.",
+    "3. The implementation is internally consistent with the repository.",
+    "4. Appropriate verification was performed.",
+    "5. Remaining failures or limitations are explicitly identified.",
+    "",
+    "Your final response should be concise and factual: summarize what changed, what was verified, and any remaining blocker."
 ].join("\n");

package/dist/tools/dir-cache.js

@@ -76,6 +76,13 @@ function toCwdRel(absDir, cwd, dirRel) {
         return dirRel;
     return `${prefix}/${dirRel}`;
 }
+// Public for the ripgrep adapter: rg emits dir-relative paths, but the
+// enumerated contract (and therefore outputs) is cwd-relative — which may
+// climb out of the tree (`../../..`) when the search dir sits outside cwd.
+// Exported so both paths share the one mapping (never duplicated logic).
+export function rgRelToCwdRel(absDir, cwd, dirRel) {
+    return toCwdRel(absDir, cwd, dirRel);
+}
 function filterSkipped(relPaths) {
     return relPaths.filter((rel) => {
         if (!rel)

package/dist/tools/filesystem.js

@@ -7,7 +7,7 @@ import { contentHash, fingerprintKey, readFingerprints } from "./fingerprints.js
 import { appendOverflow } from "./overflow.js";
 import { getCachedRead, invalidatePath, normalizeReadWindow, setCachedRead } from "./read-cache.js";
 import { invalidateListingsForFile } from "./dir-cache.js";
-import { err, invalidCall, READ_CHAR_CAP, resolveSandbox } from "./shared.js";
+import { err, invalidCall, READ_CHAR_CAP, resolveSandbox, truncateHead } from "./shared.js";
 // offset/limit are 1-based line numbers. Output capped at ~64KB.
 export async function readTool(args, cwd = process.cwd()) {
     try {
@@ -58,7 +58,8 @@ export async function readTool(args, cwd = process.cwd()) {
         let out = window.map((line, i) => `${offset + i}: ${line}`).join("\n");
         if (out.length > READ_CHAR_CAP) {
             const full = out;
-            out = appendOverflow(full.slice(0, READ_CHAR_CAP), "\n[truncated: output exceeded 64KB]", "file output", full);
+            const t = truncateHead(full, READ_CHAR_CAP, "\n[truncated: output exceeded 64KB]");
+            out = appendOverflow(t.head, t.note, "file output", full);
         }
         try {
             const statInfo = { mtimeMs: st.mtimeMs ?? 0, size: st.size ?? 0 };

package/dist/tools/registry.js

@@ -574,6 +574,7 @@ export const TOOL_DEFINITIONS = [
                 "runInBackground=true for servers/watchers/slow builds, then poll with bash_output. " +
                 "WHEN NOT to use: never for reading/writing/searching files; never destructive or exfiltrating without explicit user approval; " +
                 "don't assume a TTY. " +
+                "Shell is cmd.exe on Windows (use dir; quote paths containing spaces) and POSIX sh elsewhere — the env block names it; never probe with ls/pwd/whoami. " +
                 "Foreground returns JSON {exitCode, stdout, stderr, timedOut, ...} (streams truncate with pointers). " +
                 "Background returns {backgroundTaskId, ...} immediately; the process keeps running detached. " +
                 "PRIVILEGED: no sandbox beyond cwd+timeout.",