@illuminis/comprism 0.1.3 → 0.1.5

package/out/executor/files.js

@@ -46,12 +46,16 @@ exports.performFileAction = performFileAction;
  * writes is easy; one that refuses correctly is the one somebody can leave
  * running.
  */
+const child_process_1 = require("child_process");
+const crypto_1 = require("crypto");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const paths_1 = require("./paths");
 const MAX_FILE_CHARS = 60_000;
 const MAX_RESULTS = 200;
 const MAX_MAP_PATHS = 2_000;
+/** Beyond this a file asked for whole is read as its first lines (manual 5.4). */
+const MAX_WHOLE_LINES = 2_000;
 const SKIP_DIRS = new Set([
     "node_modules", ".git", "dist", "build", "out", ".next", ".nuxt", ".venv",
     "venv", "env", "__pycache__", ".pytest_cache", ".mypy_cache", "coverage",
@@ -65,6 +69,8 @@ const TEXT_EXT = new Set([
     "ini", "cfg", "conf", "md", "mdx", "txt", "rst", "csv", "tsv", "xml", "svg",
     "vue", "svelte", "astro", "graphql", "gql", "proto", "lock", "prisma", "tf",
     "r", "jl", "lua", "pl", "ex", "exs",
+    // Logs are the commonest large text file a person asks about (manual 6.13).
+    "log",
 ]);
 function isText(name) {
     const lower = name.toLowerCase();
@@ -78,7 +84,13 @@ function ok(content, summary) {
 function fail(content) {
     return { content, isError: true, summary: content.slice(0, 200) };
 }
-function walk(dir, root, out, limit) {
+/** A project path as the agent sees it: forward slashes on every system.
+ *  Windows would otherwise hand back `src\math.py`, which no pattern the model
+ *  writes will ever match (manual 5.2). */
+function slashed(rel) {
+    return rel.split(path.sep).join("/");
+}
+function walk(dir, root, out, limit, all = false) {
     if (out.length >= limit)
         return;
     let entries;
@@ -93,19 +105,89 @@ function walk(dir, root, out, limit) {
             return;
         const full = path.join(dir, e.name);
         if (e.isDirectory()) {
-            if (SKIP_DIRS.has(e.name))
+            // Git's own folder is never project content, even when asked for all.
+            if (e.name === ".git" || (!all && SKIP_DIRS.has(e.name)))
                 continue;
             // Not followed. A link pointing outside the project would otherwise pull
             // the whole machine into a file map, and `resolveInside` would never see
             // it because nobody asked for that path by name.
             if (e.isSymbolicLink())
                 continue;
-            walk(full, root, out, limit);
+            walk(full, root, out, limit, all);
         }
         else if (e.isFile()) {
-            out.push(path.relative(root, full));
+            out.push(slashed(path.relative(root, full)));
+        }
+    }
+}
+/** Paths the service said to leave out of a search or listing, because a
+ *  `deny` rule covers them (manual 4.11). The service decides; this only skips
+ *  them, so nothing from a denied folder is read. The service still removes
+ *  anything that slips through from what comes back. */
+function denied(rel, exclude) {
+    if (!Array.isArray(exclude) || exclude.length === 0)
+        return false;
+    return exclude.some((raw) => {
+        const pattern = String(raw);
+        const base = pattern.endsWith("/**") ? pattern.slice(0, -3) : null;
+        if (base !== null && (rel === base || rel.startsWith(`${base}/`)))
+            return true;
+        return globToRegExp(pattern).test(rel);
+    });
+}
+/** What git itself would call this project's files: tracked, plus new files
+ *  that `.gitignore` does not exclude. Git reads every ignore file, nested and
+ *  global, so nothing here reimplements its rules. Null outside a repository,
+ *  or when git is not installed, and the plain walk is used instead. */
+function gitFiles(dir, root) {
+    let listed;
+    try {
+        // An argument list, never a shell string (COMMON.md, Windows quoting).
+        listed = (0, child_process_1.execFileSync)("git", ["ls-files", "-z", "--cached", "--others", "--exclude-standard"], {
+            cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
+            maxBuffer: 64 * 1024 * 1024, windowsHide: true,
+        });
+    }
+    catch {
+        return null;
+    }
+    const out = [];
+    for (const rel of listed.split("\0")) {
+        if (!rel)
+            continue;
+        // Dependency and build folders stay out even if someone committed them.
+        if (rel.split("/").some((part) => SKIP_DIRS.has(part)))
+            continue;
+        const full = path.join(dir, rel);
+        // A tracked file that was deleted, or a link, is not a file to read.
+        try {
+            if (!fs.lstatSync(full).isFile())
+                continue;
         }
+        catch {
+            continue;
+        }
+        out.push(slashed(path.relative(root, full)));
+    }
+    return out;
+}
+/** The files under `dir` a search looks at. Ignored files, dependency folders
+ *  and build output are left out unless `all` is asked for (manual 5.2). */
+function projectFiles(dir, root, limit, all) {
+    // A search limited to one file searches that file (manual 5.3).
+    try {
+        if (fs.statSync(dir).isFile())
+            return [slashed(path.relative(root, dir))];
+    }
+    catch {
+        return [];
     }
+    const listed = all ? null : gitFiles(dir, root);
+    if (listed)
+        return listed.sort().slice(0, limit);
+    const out = [];
+    walk(dir, root, out, limit, all);
+    return out.sort();
 }
 function globToRegExp(pattern) {
     let out = "";
@@ -128,6 +210,43 @@ function globToRegExp(pattern) {
     }
     return new RegExp(`^${out}$`);
 }
+/** What each file held when the agent last read or wrote it, by real path, so
+ *  an edit whose target has gone can say the file changed since it was read
+ *  (manual 5.6). Only a fingerprint is kept, never the text. */
+const seen = new Map();
+function fingerprint(text) {
+    return (0, crypto_1.createHash)("sha256").update(text).digest("hex");
+}
+/** Lines taken out and put in by replacing `from` with `to`. */
+function linesIn(text) {
+    if (!text)
+        return 0;
+    return text.split("\n").length - (text.endsWith("\n") ? 1 : 0);
+}
+/** Lines really taken out and put in: lines the edit repeated unchanged at
+ *  either end, for context, are not counted as changed (manual 5.6). */
+function trimmedCounts(from, to) {
+    const a = from.replace(/\n$/, "").split("\n");
+    const b = to.replace(/\n$/, "").split("\n");
+    if (!from)
+        return [0, linesIn(to)];
+    if (!to)
+        return [linesIn(from), 0];
+    let head = 0;
+    while (head < a.length && head < b.length && a[head] === b[head])
+        head += 1;
+    let tail = 0;
+    while (tail < a.length - head && tail < b.length - head
+        && a[a.length - 1 - tail] === b[b.length - 1 - tail])
+        tail += 1;
+    return [a.length - head - tail, b.length - head - tail];
+}
+function lineCounts(from, to) {
+    const [removed, added] = trimmedCounts(from, to);
+    return { changed: 1, lines_removed: removed, lines_added: added };
+}
+const STALE = (rel) => `Refused, and nothing was written: the file changed since it was read. ${rel} no longer holds that text, `
+    + "so somebody or something else edited it. Read it again and edit what is there now.";
 function countOf(haystack, needle) {
     if (!needle)
         return 0;
@@ -152,40 +271,89 @@ function performFileAction(root, name, a) {
                     const size = fs.statSync(p).size;
                     return fail(`${rel} is not a text file (${size.toLocaleString()} bytes). Reading it would be noise rather than context.`);
                 }
-                let body = fs.readFileSync(p, "utf8");
+                const whole = fs.readFileSync(p, "utf8");
+                seen.set(p, fingerprint(whole));
+                const lines = whole.split("\n");
+                // A file ending in a newline has no line after it.
+                if (lines.length > 1 && lines[lines.length - 1] === "")
+                    lines.pop();
+                const total = lines.length;
                 const offset = Number(a.offset ?? 0), limit = Number(a.limit ?? 0);
-                if (offset > 0 || limit > 0) {
-                    const lines = body.split("\n");
-                    const from = Math.max(0, offset > 0 ? offset - 1 : 0);
-                    body = lines.slice(from, limit > 0 ? from + limit : undefined).join("\n");
-                }
+                const ranged = offset > 0 || limit > 0;
+                // Small files are read whole. A large one asked for whole gets its
+                // first lines and is told how to reach the rest, so a 5,000 line file
+                // never lands in the conversation entire (manual 5.4).
+                const large = total > MAX_WHOLE_LINES || whole.length > MAX_FILE_CHARS;
+                const from = Math.min(Math.max(0, offset > 0 ? offset - 1 : 0), total);
+                let to = ranged ? (limit > 0 ? Math.min(total, from + limit) : total)
+                    : large ? Math.min(total, MAX_WHOLE_LINES) : total;
+                let body = lines.slice(from, to).join("\n");
                 if (body.length > MAX_FILE_CHARS) {
-                    body = `${body.slice(0, MAX_FILE_CHARS)}\n\n[... truncated. Use offset and limit to read further.]`;
+                    // Cut on a line, so the range reported is the range given.
+                    let size = 0, kept = from;
+                    while (kept < to && size + lines[kept].length + 1 <= MAX_FILE_CHARS) {
+                        size += lines[kept].length + 1;
+                        kept += 1;
+                    }
+                    to = Math.max(kept, from + 1);
+                    body = lines.slice(from, to).join("\n");
+                }
+                const n = (x) => x.toLocaleString("en-US");
+                if (to < total || from > 0) {
+                    body += `\n\n[Lines ${n(from + 1)} to ${n(to)} of ${n(total)}. `
+                        + "Use grep to find what you need, then offset and limit to read just those lines.]";
                 }
-                return ok(body, `read ${rel}`);
+                return {
+                    content: body,
+                    summary: `read ${rel} lines ${n(from + 1)} to ${n(to)} of ${n(total)}`,
+                    facts: { lines_from: total ? from + 1 : 0, lines_to: to, lines_total: total },
+                };
             }
             case "list_dir": {
                 const p = (0, paths_1.resolveInside)(realRoot, String(a.path ?? ""), true);
+                const here = slashed(path.relative(realRoot, p));
                 const rows = fs.readdirSync(p, { withFileTypes: true })
+                    .filter((e) => !denied(here ? `${here}/${e.name}` : e.name, a.exclude))
                     .map((e) => (e.isDirectory() ? `${e.name}/` : e.name)).sort();
                 return ok(rows.join("\n") || "(empty)", `${rows.length} entries`);
             }
             case "file_map": {
                 const p = (0, paths_1.resolveInside)(realRoot, String(a.path ?? ""), true);
-                const found = [];
-                walk(p, realRoot, found, MAX_MAP_PATHS);
-                found.sort();
-                const note = found.length >= MAX_MAP_PATHS
-                    ? `\n\n[... stopped at ${MAX_MAP_PATHS} paths. Map a subfolder for the rest.]` : "";
-                return ok(found.join("\n") + note, `${found.length} files`);
+                const found = projectFiles(p, realRoot, Number.MAX_SAFE_INTEGER, Boolean(a.include_ignored))
+                    .filter((f) => !denied(f, a.exclude));
+                const shown = found.slice(0, MAX_MAP_PATHS);
+                const note = found.length > shown.length
+                    ? `\n\n[... ${found.length - shown.length} more paths left out. Map a subfolder for the rest.]` : "";
+                return {
+                    content: shown.join("\n") + note, summary: `${found.length} files`,
+                    facts: { files: shown.length, left_out: found.length - shown.length },
+                };
             }
             case "glob": {
                 const p = (0, paths_1.resolveInside)(realRoot, String(a.path ?? ""), true);
-                const found = [];
-                walk(p, realRoot, found, MAX_MAP_PATHS);
-                const rx = globToRegExp(String(a.pattern ?? ""));
-                const hits = found.filter((f) => rx.test(f)).slice(0, MAX_RESULTS);
-                return ok(hits.join("\n") || "(no matches)", `${hits.length} files`);
+                const found = projectFiles(p, realRoot, Number.MAX_SAFE_INTEGER, Boolean(a.include_ignored))
+                    .filter((f) => !denied(f, a.exclude));
+                const pattern = String(a.pattern ?? "");
+                const rx = globToRegExp(pattern);
+                // A bare name pattern ("calc.py", "*.py") means anywhere in the
+                // project, the way a person reads it, not only the top folder.
+                const anywhere = pattern.includes("/") ? null : globToRegExp(`**/${pattern}`);
+                const all = found.filter((f) => rx.test(f) || Boolean(anywhere?.test(f)));
+                // Newest first, as the tool description promises.
+                const mtime = (f) => { try {
+                    return fs.statSync(path.join(realRoot, f)).mtimeMs;
+                }
+                catch {
+                    return 0;
+                } };
+                const hits = all.map((f) => [f, mtime(f)])
+                    .sort((x, y) => y[1] - x[1]).slice(0, MAX_RESULTS).map(([f]) => f);
+                const note = all.length > hits.length
+                    ? `\n\n[... ${all.length - hits.length} more files left out. Narrow the pattern.]` : "";
+                return {
+                    content: (hits.join("\n") || "(no matches)") + note, summary: `${all.length} files`,
+                    facts: { files: hits.length, left_out: all.length - hits.length },
+                };
             }
             case "grep": {
                 const p = (0, paths_1.resolveInside)(realRoot, String(a.path ?? ""), true);
@@ -196,18 +364,22 @@ function performFileAction(root, name, a) {
                 catch (e) {
                     return fail(`That is not a valid regular expression: ${e.message}`);
                 }
-                const globRx = a.glob ? globToRegExp(String(a.glob)) : null;
-                const files = [];
-                walk(p, realRoot, files, MAX_MAP_PATHS);
+                const globText = a.glob ? String(a.glob) : "";
+                const globRx = globText ? globToRegExp(globText) : null;
+                const globAnywhere = globText && !globText.includes("/") ? globToRegExp(`**/${globText}`) : null;
+                const files = projectFiles(p, realRoot, Number.MAX_SAFE_INTEGER, Boolean(a.include_ignored))
+                    .filter((f) => !denied(f, a.exclude));
                 const context = Math.max(0, Math.min(Number(a.context_lines ?? 0), 5));
                 const hits = [];
+                // Every match is counted, even past the cap, so the agent is told how
+                // many it did not see and can narrow the search (manual 5.3).
+                let matches = 0;
+                const matchedFiles = new Set();
                 for (const rel of files) {
-                    if (hits.length >= MAX_RESULTS)
-                        break;
                     const leaf = path.basename(rel);
                     if (!isText(leaf) || (0, paths_1.isSecret)(leaf))
                         continue;
-                    if (globRx && !globRx.test(rel))
+                    if (globRx && !globRx.test(rel) && !globAnywhere?.test(rel))
                         continue;
                     let text;
                     try {
@@ -217,9 +389,13 @@ function performFileAction(root, name, a) {
                         continue;
                     }
                     const lines = text.split("\n");
-                    for (let i = 0; i < lines.length && hits.length < MAX_RESULTS; i += 1) {
+                    for (let i = 0; i < lines.length; i += 1) {
                         if (!rx.test(lines[i]))
                             continue;
+                        matches += 1;
+                        matchedFiles.add(rel);
+                        if (hits.length >= MAX_RESULTS)
+                            continue;
                         if (context === 0)
                             hits.push(`${rel}:${i + 1}:${lines[i]}`);
                         else {
@@ -228,8 +404,15 @@ function performFileAction(root, name, a) {
                         }
                     }
                 }
-                const note = hits.length >= MAX_RESULTS ? `\n\n[... stopped at ${MAX_RESULTS} matches. Narrow the search.]` : "";
-                return ok(hits.join("\n") + note || "(no matches)", `${hits.length} matches`);
+                const leftOut = matches - hits.length;
+                const note = leftOut > 0
+                    ? `\n\n[Showing ${hits.length} of ${matches.toLocaleString("en-US")} matches in ${matchedFiles.size} files; ${leftOut.toLocaleString("en-US")} left out. Narrow the pattern, the folder or the glob.]`
+                    : "";
+                return {
+                    content: (hits.join("\n") || "(no matches)") + note,
+                    summary: `${matches} matches`,
+                    facts: { matches: hits.length, left_out: leftOut, files: matchedFiles.size },
+                };
             }
             // Bytes rather than text, and the ONLY caller is the server writing a
             // document it just built. A Word file, a deck or a PDF is not text, so it
@@ -275,11 +458,21 @@ function performFileAction(root, name, a) {
                 // watching knows that a file they already had was just replaced. "wrote"
                 // reads identically in both cases and hides exactly the one that matters.
                 const replaced = fs.existsSync(p);
+                const lineCount = content.split("\n").length - (content.endsWith("\n") ? 1 : 0);
+                if (replaced && fs.readFileSync(p, "utf8") === content) {
+                    seen.set(p, fingerprint(content));
+                    return {
+                        content: `No change: ${rel} already holds exactly this. Nothing was written.`,
+                        summary: `no change ${rel}`, facts: { changed: 0, created: 0, lines: lineCount },
+                    };
+                }
                 fs.writeFileSync(p, content, "utf8");
+                seen.set(p, fingerprint(content));
                 const size = `${content.length.toLocaleString()} characters`;
+                const facts = { changed: 1, created: replaced ? 0 : 1, lines: lineCount };
                 return replaced
-                    ? ok(`Rewrote ${rel}, replacing what was there (${size}).`, `rewrote ${rel}`)
-                    : ok(`Created ${rel} (${size}).`, `created ${rel}`);
+                    ? { ...ok(`Rewrote ${rel}, replacing what was there (${size}).`, `rewrote ${rel}`), facts }
+                    : { ...ok(`Created ${rel} (${size}).`, `created ${rel}`), facts };
             }
             case "edit_file": {
                 const rel = String(a.path ?? "");
@@ -288,6 +481,10 @@ function performFileAction(root, name, a) {
                 const oldText = String(a.old_text ?? "");
                 const n = countOf(text, oldText);
                 if (n === 0) {
+                    // Read before, and different now: somebody else changed it.
+                    const before = seen.get(p);
+                    if (before && before !== fingerprint(text))
+                        return fail(STALE(rel));
                     return fail(`Refused: that exact text is not in ${rel}. Read the file again — whitespace and indentation have to match exactly.`);
                 }
                 if (n > 1) {
@@ -300,8 +497,19 @@ function performFileAction(root, name, a) {
                 if (a.new_text === undefined || a.new_text === null) {
                     return fail(`Refused, and nothing was changed: edit_file was called for ${rel} with no replacement text. Send "new_text". To delete the matched section, pass an empty string.`);
                 }
-                fs.writeFileSync(p, text.replace(oldText, String(a.new_text)), "utf8");
-                return ok(`Edited ${rel}.`, `edited ${rel}`);
+                const newText = String(a.new_text);
+                if (newText === oldText) {
+                    return {
+                        content: `No change: the replacement is the same as the text already in ${rel}. Nothing was written.`,
+                        summary: `no change ${rel}`, facts: { changed: 0 },
+                    };
+                }
+                // A function as the replacement, so a `$` in the new text is written
+                // as a `$` and never read as a pattern.
+                const next = text.replace(oldText, () => newText);
+                fs.writeFileSync(p, next, "utf8");
+                seen.set(p, fingerprint(next));
+                return { ...ok(`Edited ${rel}.`, `edited ${rel}`), facts: lineCounts(oldText, newText) };
             }
             case "multi_edit": {
                 const rel = String(a.path ?? "");
@@ -311,6 +519,11 @@ function performFileAction(root, name, a) {
                 for (let i = 0; i < edits.length; i += 1) {
                     const from = String(edits[i].old_text ?? "");
                     const n = countOf(next, from);
+                    if (n === 0 && i === 0) {
+                        const before = seen.get(p);
+                        if (before && before !== fingerprint(next))
+                            return fail(STALE(rel));
+                    }
                     if (n !== 1) {
                         return fail(`Refused, and nothing was changed: edit ${i + 1} of ${edits.length} matches ${n} times in ${rel}. Every edit has to match exactly once.`);
                     }
@@ -320,10 +533,24 @@ function performFileAction(root, name, a) {
                     if (to === undefined || to === null) {
                         return fail(`Refused, and nothing was changed: edit ${i + 1} of ${edits.length} for ${rel} has no replacement text. Send "new_text". To delete the matched section, pass an empty string.`);
                     }
-                    next = next.replace(from, String(to));
+                    next = next.replace(from, () => String(to));
+                }
+                const original = fs.readFileSync(p, "utf8");
+                if (next === original) {
+                    return {
+                        content: `No change: those edits leave ${rel} exactly as it was. Nothing was written.`,
+                        summary: `no change ${rel}`, facts: { changed: 0 },
+                    };
                 }
                 fs.writeFileSync(p, next, "utf8");
-                return ok(`Applied ${edits.length} edits to ${rel}.`, `${edits.length} edits`);
+                seen.set(p, fingerprint(next));
+                const counted = edits.map((e) => trimmedCounts(String(e.old_text ?? ""), String(e.new_text ?? "")));
+                const removed = counted.reduce((t, c) => t + c[0], 0);
+                const added = counted.reduce((t, c) => t + c[1], 0);
+                return {
+                    ...ok(`Applied ${edits.length} edits to ${rel}.`, `${edits.length} edits`),
+                    facts: { changed: 1, lines_removed: removed, lines_added: added },
+                };
             }
             case "create_dir": {
                 const rel = String(a.path ?? "");
@@ -348,8 +575,11 @@ function performFileAction(root, name, a) {
         }
     }
     catch (err) {
-        if (err instanceof paths_1.OutsideWorkspace)
-            return fail(err.message);
+        // The whole refusal, path and real location included, however long the
+        // path (manual 2.4). An ordinary failure summary stops at 200 characters.
+        if (err instanceof paths_1.OutsideWorkspace) {
+            return { content: err.message, isError: true, summary: err.message.slice(0, 2000) };
+        }
         const e = err;
         if (e.code === "ENOENT")
             return fail(`No such file: ${a.path ?? ""}`);

package/out/executor/git.js

@@ -26,47 +26,45 @@ exports.gitPush = gitPush;
  * being reimplemented for git.
  */
 const shell_1 = require("./shell");
-/** Arguments passed as a list and quoted, never interpolated into a string.
+/** Every git call is a program and a list of arguments, with no shell.
  *
  *  A commit message is written by a model and can contain anything: quotes,
  *  backticks, a newline, a semicolon. Pasting one into a shell string is how a
- *  message becomes a second command. */
-function quote(value) {
-    return `'${String(value).replace(/'/g, `'\\''`)}'`;
-}
+ *  message becomes a second command, and quoting it for one shell broke it on
+ *  another: Windows kept the POSIX quotes as part of the message. */
+const git = (args, opts) => (0, shell_1.runProgram)("git", args, opts);
 async function gitStatus(opts) {
     // Porcelain, because the human-readable format changes between versions and
     // the model has to be able to rely on the shape.
-    const r = await (0, shell_1.runCommand)("git status --porcelain=v1 --branch", opts);
+    const r = await git(["status", "--porcelain=v1", "--branch"], opts);
     if (!r.isError && /^exit 0/.test(r.content) && r.content.trim().split("\n").length <= 3) {
         return { ...r, content: `${r.content}\n\n[Nothing has changed in the working tree.]` };
     }
     return r;
 }
 async function gitDiff(opts) {
-    const parts = ["git", "--no-pager", "diff"];
+    const parts = ["--no-pager", "diff"];
     if (opts.staged)
         parts.push("--staged");
     // Color off explicitly: a diff full of escape codes costs tokens and reads
     // as noise to a model.
     parts.push("--no-color");
     if (opts.path)
-        parts.push("--", quote(opts.path));
-    return (0, shell_1.runCommand)(parts.join(" "), opts);
+        parts.push("--", opts.path);
+    return git(parts, opts);
 }
 async function gitLog(opts) {
     const limit = Math.max(1, Math.min(opts.limit ?? 20, 100));
     const parts = [
-        "git", "--no-pager", "log", `-n ${limit}`,
-        // Quoted. Everything here goes through a shell, so an unquoted format string
-        // is split on its spaces and git reads "%an" as a revision. It fails with
-        // "ambiguous argument", which reads like a broken repository rather than a
-        // quoting mistake, and cost a test run to diagnose.
-        `--pretty=${quote("format:%h %an %ar %s")}`,
+        "--no-pager", "log", "-n", String(limit),
+        // One argument, spaces and all. When this went through a shell it had to be
+        // quoted, or git read "%an" as a revision and failed with "ambiguous
+        // argument", which reads like a broken repository.
+        "--pretty=format:%h %an %ar %s",
     ];
     if (opts.path)
-        parts.push("--", quote(opts.path));
-    return (0, shell_1.runCommand)(parts.join(" "), opts);
+        parts.push("--", opts.path);
+    return git(parts, opts);
 }
 async function gitBranch(name, opts) {
     if (!/^[\w./-]{1,120}$/.test(name)) {
@@ -75,21 +73,27 @@ async function gitBranch(name, opts) {
             content: `Refused: ${name} is not a usable branch name. Letters, numbers, dots, dashes, underscores and slashes only.`,
         };
     }
-    return (0, shell_1.runCommand)(`git checkout -b ${quote(name)}`, opts);
+    return git(["checkout", "-b", name], opts);
 }
 async function gitCommit(message, opts) {
     if (!message.trim()) {
         return { isError: true, content: "Refused: a commit needs a message." };
     }
-    const stage = opts.paths?.length
-        ? `git add -- ${opts.paths.map(quote).join(" ")}`
-        : "git add -A";
-    const staged = await (0, shell_1.runCommand)(stage, opts);
-    if (staged.isError)
-        return staged;
+    // Only the files named: what the agent changed, or what the person named.
+    // Never "add everything", which would sweep in the person's own unrelated
+    // work (manual 5.17).
+    if (!opts.paths?.length) {
+        return {
+            isError: true,
+            content: "Refused: nothing to commit that this session changed. Name the files to commit.",
+        };
+    }
+    const staged = await git(["add", "--", ...opts.paths], opts);
+    if (staged.isError || !/^exit 0/.test(staged.content))
+        return { ...staged, isError: true };
     // Nothing to commit is a normal outcome, not a failure. Reported plainly so
     // the model does not conclude that committing is broken and try again.
-    const check = await (0, shell_1.runCommand)("git diff --staged --quiet", opts);
+    const check = await git(["diff", "--staged", "--quiet"], opts);
     if (/^exit 0\b/.test(check.content)) {
         return { content: "Nothing to commit: no changes are staged.", summary: "nothing to commit" };
     }
@@ -97,7 +101,13 @@ async function gitCommit(message, opts) {
     // a commit somebody later reads as a colleague's careful work, and the whole
     // record this product keeps depends on that not happening.
     const trailer = "\n\nCo-authored-by: illuminis coding agent <agent@illuminis.ai>";
-    return (0, shell_1.runCommand)(`git commit -m ${quote(message + trailer)}`, opts);
+    const made = await git(["commit", "-m", message + trailer], opts);
+    // A commit hook that refused it is a failed commit, said so (manual 5.17).
+    // Its output is the reason; what was staged is left staged for the person.
+    if (!/^exit 0/.test(made.content)) {
+        return { ...made, isError: true, summary: "commit failed", content: `Commit failed. ${made.content}` };
+    }
+    return { ...made, summary: `committed ${opts.paths.join(", ")}` };
 }
 /** Send commits to the remote.
  *
@@ -117,11 +127,14 @@ async function gitPush(branch, opts) {
     }
     // What is about to go, named before it goes. A push that reports success
     // without saying what it sent is a push nobody can check afterwards.
-    const ahead = await (0, shell_1.runCommand)(`git --no-pager log --oneline origin/${quote(branch)}..HEAD 2>/dev/null || git --no-pager log --oneline -5`, opts);
+    // A branch the remote has not seen yet has no range to compare with, so the
+    // last five commits stand in for it.
+    let ahead = await git(["--no-pager", "log", "--oneline", `origin/${branch}..HEAD`], opts);
+    if (!/^exit 0/.test(ahead.content))
+        ahead = await git(["--no-pager", "log", "--oneline", "-5"], opts);
     // `-u` on a new branch so later pushes need no arguments, and nothing else.
     // No `--force`, no `--force-with-lease`, no `+refs` refspec.
-    const flags = opts.createRemote ? "-u" : "";
-    const pushed = await (0, shell_1.runCommand)(`git push ${flags} origin ${quote(branch)}`.replace(/\s+/g, " "), opts);
+    const pushed = await git(["push", ...(opts.createRemote ? ["-u"] : []), "origin", branch], opts);
     if (pushed.isError || !/^exit 0/.test(pushed.content)) {
         return { ...pushed, isError: true };
     }