@glbgpt/cli 0.1.4 → 0.2.1

package/dist/src/coding/dangerousCommands.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Dangerous-command heuristics for the bash approval gate (codex lineage,
+ * 2026-08-21 dossier). Two independent judgments:
+ *
+ * - {@link isDangerousCommand}: commands that must ALWAYS be confirmed one at a
+ *   time and can never enter the session allowlist (forced/recursive rm, sudo,
+ *   raw device writes...). Wrappers (sudo/env/nice/...) are recursively unwrapped
+ *   with a depth cap that fails CLOSED (too deeply wrapped = dangerous).
+ *
+ * - {@link isBannedAllowlistPrefix}: prefixes that must never become standing
+ *   allowlist rules because approving them approves arbitrary code execution
+ *   (bare shells, interpreter evals, env, rm, bare git/npm...). The command can
+ *   still be approved ONCE — it just never gets a "don't ask again" rule.
+ */
+/** Naive whitespace tokenizer that keeps quoted spans intact (conservative — good enough for judging). */
+export declare function tokenize(command: string): string[];
+/** The effective base tokens after unwrapping (depth-capped). Null = too wrapped, treat as dangerous. */
+export declare function unwrapCommand(command: string): string[] | null;
+/** True when the command contains shell control operators / redirections (top-level or not — conservative). */
+export declare function isCompoundCommand(command: string): boolean;
+export declare function isDangerousCommand(command: string): boolean;
+/**
+ * The standing-allowlist prefix for a command: its first two tokens (or the single
+ * token for a one-token command). Returns null when no safe prefix exists — the
+ * command may still be approved once, but never remembered.
+ */
+export declare function allowlistPrefixFor(command: string): string | null;
+/** Claude Code prefix-match semantics: word boundary, and NEVER against a compound command. */
+export declare function matchesAllowlistPrefix(command: string, prefix: string): boolean;

package/dist/src/coding/dangerousCommands.js

@@ -0,0 +1,156 @@
+/**
+ * Dangerous-command heuristics for the bash approval gate (codex lineage,
+ * 2026-08-21 dossier). Two independent judgments:
+ *
+ * - {@link isDangerousCommand}: commands that must ALWAYS be confirmed one at a
+ *   time and can never enter the session allowlist (forced/recursive rm, sudo,
+ *   raw device writes...). Wrappers (sudo/env/nice/...) are recursively unwrapped
+ *   with a depth cap that fails CLOSED (too deeply wrapped = dangerous).
+ *
+ * - {@link isBannedAllowlistPrefix}: prefixes that must never become standing
+ *   allowlist rules because approving them approves arbitrary code execution
+ *   (bare shells, interpreter evals, env, rm, bare git/npm...). The command can
+ *   still be approved ONCE — it just never gets a "don't ask again" rule.
+ */
+const WRAPPERS = new Set(['sudo', 'doas', 'env', 'nice', 'nohup', 'time', 'stdbuf', 'timeout', 'command']);
+/** First tokens that make a standing allowlist rule equivalent to "allow everything". */
+const BANNED_PREFIX_FIRST_TOKENS = new Set([
+    'sh',
+    'bash',
+    'zsh',
+    'dash',
+    'ksh',
+    'fish',
+    'pwsh',
+    'powershell',
+    'node',
+    'python',
+    'python3',
+    'perl',
+    'ruby',
+    'php',
+    'deno',
+    'bun',
+    'npx',
+    'uvx',
+    'eval',
+    'exec',
+    'source',
+    'xargs',
+    'sudo',
+    'doas',
+    'env',
+    'rm',
+    'ssh',
+]);
+/** Broad tool launchers: a ONE-word prefix is too permissive, two words (git status) is fine. */
+const TOO_BROAD_ALONE = new Set(['git', 'npm', 'yarn', 'pnpm', 'docker', 'kubectl', 'make', 'mvn', 'gradle']);
+/** Naive whitespace tokenizer that keeps quoted spans intact (conservative — good enough for judging). */
+export function tokenize(command) {
+    const tokens = command.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) ?? [];
+    return tokens.map((t) => t.trim()).filter((t) => t.length > 0);
+}
+/** Drop leading VAR=value assignments (so `FOO=1 rm -rf /` is judged as rm). */
+function stripAssignments(tokens) {
+    let i = 0;
+    while (i < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i]))
+        i += 1;
+    return tokens.slice(i);
+}
+/** Unwrap one wrapper layer (sudo/env/... plus their obvious flags/operands). */
+function unwrapOnce(tokens) {
+    const t = stripAssignments(tokens);
+    if (t.length === 0 || !WRAPPERS.has(t[0]))
+        return t === tokens ? null : t;
+    let rest = t.slice(1);
+    // Skip wrapper flags; for `timeout` also its duration operand; for env, assignments.
+    while (rest.length > 0 && (rest[0].startsWith('-') || /^[A-Za-z_][A-Za-z0-9_]*=/.test(rest[0]))) {
+        rest = rest.slice(1);
+    }
+    if (t[0] === 'timeout' && rest.length > 0 && /^\d/.test(rest[0]))
+        rest = rest.slice(1);
+    return rest;
+}
+/** The effective base tokens after unwrapping (depth-capped). Null = too wrapped, treat as dangerous. */
+export function unwrapCommand(command) {
+    let tokens = tokenize(command);
+    for (let depth = 0; depth < 8; depth++) {
+        const next = unwrapOnce(tokens);
+        if (next === null)
+            return tokens;
+        if (next.length === 0)
+            return next;
+        if (next === tokens || next[0] === tokens[0])
+            return next;
+        tokens = next;
+    }
+    return null; // fail closed
+}
+/** True when the command contains shell control operators / redirections (top-level or not — conservative). */
+export function isCompoundCommand(command) {
+    return /(\|\||&&|;|\||&|>|<|\n|`|\$\()/.test(command);
+}
+function rmIsForcedOrRecursive(tokens) {
+    return tokens.some((t) => t === '--force' ||
+        t === '--recursive' ||
+        (/^-[a-zA-Z]+$/.test(t) && (t.includes('r') || t.includes('R') || t.includes('f'))));
+}
+/** Segment a compound command on control operators so each piece is judged separately. */
+function segments(command) {
+    return command
+        .split(/\|\||&&|;|\||\n/)
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+export function isDangerousCommand(command) {
+    for (const seg of segments(command)) {
+        const tokens = unwrapCommand(seg);
+        if (tokens === null)
+            return true; // unwrap depth exhausted — fail closed
+        if (tokens.length === 0)
+            continue;
+        const raw = tokenize(seg);
+        const base = tokens[0];
+        if (raw[0] === 'sudo' || raw[0] === 'doas')
+            return true;
+        if (base === 'rm' && rmIsForcedOrRecursive(tokens))
+            return true;
+        if (base === 'mkfs' || base.startsWith('mkfs.'))
+            return true;
+        if (base === 'shutdown' || base === 'reboot' || base === 'halt')
+            return true;
+        if (base === 'dd' && tokens.some((t) => t.startsWith('of=/dev/')))
+            return true;
+        if ((base === 'chmod' || base === 'chown') && tokens.some((t) => t === '777' || t.endsWith(':777'))) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * The standing-allowlist prefix for a command: its first two tokens (or the single
+ * token for a one-token command). Returns null when no safe prefix exists — the
+ * command may still be approved once, but never remembered.
+ */
+export function allowlistPrefixFor(command) {
+    if (isCompoundCommand(command) || isDangerousCommand(command))
+        return null;
+    const tokens = tokenize(command);
+    if (tokens.length === 0)
+        return null;
+    if (BANNED_PREFIX_FIRST_TOKENS.has(tokens[0]))
+        return null;
+    if (tokens.length === 1) {
+        return TOO_BROAD_ALONE.has(tokens[0]) ? null : tokens[0];
+    }
+    if (tokens[1].startsWith('-'))
+        return tokens[0]; // flags are not a subcommand
+    return `${tokens[0]} ${tokens[1]}`;
+}
+/** Claude Code prefix-match semantics: word boundary, and NEVER against a compound command. */
+export function matchesAllowlistPrefix(command, prefix) {
+    if (isCompoundCommand(command))
+        return false;
+    return command === prefix || command.startsWith(prefix + ' ');
+}
+//# sourceMappingURL=dangerousCommands.js.map

package/dist/src/coding/dangerousCommands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dangerousCommands.js","sourceRoot":"","sources":["../../../src/coding/dangerousCommands.ts"],"names":[],"mappings":"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"}

package/dist/src/coding/editDiff.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Matching + application logic for edit_file (pi contract, 2026-08-21 dossier):
+ * every edit matches against the ORIGINAL file, must be found exactly once, edits
+ * must not overlap, and the combined result must differ from the original. Exact
+ * matching first; a conservative line-based fuzzy fallback absorbs the classic
+ * model slips (smart quotes, unicode dashes/spaces, trailing whitespace) while
+ * preserving the original bytes of every untouched line.
+ */
+export interface EditSpec {
+    oldText: string;
+    newText: string;
+}
+export interface PlannedReplacement {
+    start: number;
+    end: number;
+    replacement: string;
+}
+export declare class EditError extends Error {
+}
+/**
+ * Normalize the model-typical transcription slips. Applied ONLY for the fuzzy
+ * fallback — never to the bytes written back.
+ */
+export declare function normalizeForFuzzy(s: string): string;
+/**
+ * Validate all edits against `content` and plan the replacements. Throws EditError
+ * with a model-actionable message on any contract violation.
+ */
+export declare function planEdits(content: string, edits: EditSpec[], pathLabel: string): PlannedReplacement[];
+/** Apply planned replacements in reverse offset order (offsets stay valid). */
+export declare function applyPlanned(content: string, planned: PlannedReplacement[]): string;
+/**
+ * A compact unified-style preview for the approval dialog: the replaced region as
+ * `-` lines and its replacement as `+` lines, per edit. UI-only — never sent to
+ * the model (token economy).
+ */
+export declare function diffPreview(content: string, planned: PlannedReplacement[], maxLines?: number): string;
+/** BOM + line-ending handling: strip for matching, restore on write-back. */
+export declare function splitBom(raw: string): {
+    bom: string;
+    text: string;
+};
+/** 'crlf' when the first newline in the file is \r\n (pi: whoever appears first wins). */
+export declare function detectLineEnding(text: string): 'crlf' | 'lf';
+export declare function restoreLineEndings(text: string, ending: 'crlf' | 'lf'): string;

package/dist/src/coding/editDiff.js

@@ -0,0 +1,156 @@
+/**
+ * Matching + application logic for edit_file (pi contract, 2026-08-21 dossier):
+ * every edit matches against the ORIGINAL file, must be found exactly once, edits
+ * must not overlap, and the combined result must differ from the original. Exact
+ * matching first; a conservative line-based fuzzy fallback absorbs the classic
+ * model slips (smart quotes, unicode dashes/spaces, trailing whitespace) while
+ * preserving the original bytes of every untouched line.
+ */
+export class EditError extends Error {
+}
+/** Positional label used in error messages: nothing for a single edit, `edits[i]` otherwise. */
+function label(i, total) {
+    return total === 1 ? 'the text' : `edits[${i}]`;
+}
+/**
+ * Normalize the model-typical transcription slips. Applied ONLY for the fuzzy
+ * fallback — never to the bytes written back.
+ */
+export function normalizeForFuzzy(s) {
+    return s
+        .replace(/[\u2018\u2019\u201A\u201B]/g, "'")
+        .replace(/[\u201C\u201D\u201E\u201F]/g, '"')
+        .replace(/[\u2010-\u2015\u2212]/g, '-')
+        .replace(/[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g, ' ')
+        .split('\n')
+        .map((l) => l.trimEnd())
+        .join('\n');
+}
+function countOccurrences(haystack, needle) {
+    let n = 0;
+    for (let i = haystack.indexOf(needle); i !== -1; i = haystack.indexOf(needle, i + 1))
+        n += 1;
+    return n;
+}
+/**
+ * Fuzzy fallback: match `oldText` as a run of WHOLE LINES whose normalized forms
+ * equal the normalized oldText lines. Returns the character range of the matched
+ * lines in the original content for each occurrence.
+ */
+function fuzzyLineMatches(content, oldText) {
+    const lines = content.split('\n');
+    const target = normalizeForFuzzy(oldText).split('\n');
+    const norm = lines.map((l) => normalizeForFuzzy(l));
+    // Precompute line start offsets in the original content.
+    const starts = new Array(lines.length);
+    let off = 0;
+    for (let i = 0; i < lines.length; i++) {
+        starts[i] = off;
+        off += lines[i].length + 1; // +1 for '\n'
+    }
+    const found = [];
+    outer: for (let i = 0; i + target.length <= norm.length; i++) {
+        for (let j = 0; j < target.length; j++) {
+            if (norm[i + j] !== target[j])
+                continue outer;
+        }
+        const last = i + target.length - 1;
+        found.push({ start: starts[i], end: starts[last] + lines[last].length });
+    }
+    return found;
+}
+/**
+ * Validate all edits against `content` and plan the replacements. Throws EditError
+ * with a model-actionable message on any contract violation.
+ */
+export function planEdits(content, edits, pathLabel) {
+    if (edits.length === 0) {
+        throw new EditError('Edit tool input is invalid. edits must contain at least one replacement.');
+    }
+    const planned = [];
+    edits.forEach((edit, i) => {
+        const who = label(i, edits.length);
+        if (edit.oldText.length === 0) {
+            const field = edits.length === 1 ? 'oldText' : `edits[${i}].oldText`;
+            throw new EditError(`${field} must not be empty in ${pathLabel}.`);
+        }
+        const exact = countOccurrences(content, edit.oldText);
+        if (exact === 1) {
+            const start = content.indexOf(edit.oldText);
+            planned.push({ start, end: start + edit.oldText.length, replacement: edit.newText });
+            return;
+        }
+        if (exact > 1) {
+            throw new EditError(`Found ${exact} occurrences of ${who} in ${pathLabel}. Each oldText must be unique. ` +
+                'Please provide more context to make it unique.');
+        }
+        // Exact miss — conservative fuzzy fallback on whole-line runs.
+        const fuzzy = fuzzyLineMatches(content, edit.oldText);
+        if (fuzzy.length === 1) {
+            planned.push({ ...fuzzy[0], replacement: edit.newText });
+            return;
+        }
+        if (fuzzy.length > 1) {
+            throw new EditError(`Found ${fuzzy.length} occurrences of ${who} in ${pathLabel}. Each oldText must be unique. ` +
+                'Please provide more context to make it unique.');
+        }
+        throw new EditError(`Could not find ${who} in ${pathLabel}. The oldText must match exactly, including all ` +
+            'whitespace and newlines. Note: read_file output prefixes each line with a line number and a ' +
+            'tab — never include that prefix in oldText.');
+    });
+    // Overlap check on the ORIGINAL-file ranges.
+    const order = planned.map((p, i) => ({ ...p, i })).sort((a, b) => a.start - b.start);
+    for (let k = 1; k < order.length; k++) {
+        if (order[k].start < order[k - 1].end) {
+            throw new EditError(`edits[${order[k - 1].i}] and edits[${order[k].i}] overlap in ${pathLabel}. ` +
+                'Merge them into one edit or target disjoint regions.');
+        }
+    }
+    return planned;
+}
+/** Apply planned replacements in reverse offset order (offsets stay valid). */
+export function applyPlanned(content, planned) {
+    const byStart = [...planned].sort((a, b) => b.start - a.start);
+    let out = content;
+    for (const p of byStart) {
+        out = out.slice(0, p.start) + p.replacement + out.slice(p.end);
+    }
+    return out;
+}
+/**
+ * A compact unified-style preview for the approval dialog: the replaced region as
+ * `-` lines and its replacement as `+` lines, per edit. UI-only — never sent to
+ * the model (token economy).
+ */
+export function diffPreview(content, planned, maxLines = 60) {
+    const parts = [];
+    const inOrder = [...planned].sort((a, b) => a.start - b.start);
+    for (const p of inOrder) {
+        const oldPart = content.slice(p.start, p.end);
+        for (const l of oldPart.split('\n'))
+            parts.push(`- ${l}`);
+        for (const l of p.replacement.split('\n'))
+            parts.push(`+ ${l}`);
+        parts.push('');
+    }
+    if (parts.at(-1) === '')
+        parts.pop();
+    if (parts.length > maxLines) {
+        const hidden = parts.length - maxLines;
+        return parts.slice(0, maxLines).join('\n') + `\n… (+${hidden} more lines)`;
+    }
+    return parts.join('\n');
+}
+/** BOM + line-ending handling: strip for matching, restore on write-back. */
+export function splitBom(raw) {
+    return raw.startsWith('\uFEFF') ? { bom: '\uFEFF', text: raw.slice(1) } : { bom: '', text: raw };
+}
+/** 'crlf' when the first newline in the file is \r\n (pi: whoever appears first wins). */
+export function detectLineEnding(text) {
+    const i = text.indexOf('\n');
+    return i > 0 && text[i - 1] === '\r' ? 'crlf' : 'lf';
+}
+export function restoreLineEndings(text, ending) {
+    return ending === 'crlf' ? text.replace(/\n/g, '\r\n') : text;
+}
+//# sourceMappingURL=editDiff.js.map

package/dist/src/coding/editDiff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"editDiff.js","sourceRoot":"","sources":["../../../src/coding/editDiff.ts"],"names":[],"mappings":"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"}

package/dist/src/coding/editTool.d.ts

@@ -0,0 +1,14 @@
+import type { ClientTool } from '../core/types.js';
+import type { PermissionGate } from './permissions.js';
+import type { ReadFileState } from './readState.js';
+/**
+ * The `edit_file` tool: exact-text replacement with a pi-contract edits[] array.
+ * All edits match against the ORIGINAL file, each must be unique and non-overlapping,
+ * and the file must have been read this session (and be unchanged since). BOM and
+ * CRLF line endings are preserved on write-back.
+ */
+export declare function createEditFileTool(opts: {
+    root: string;
+    gate: PermissionGate;
+    readState: ReadFileState;
+}): ClientTool;

package/dist/src/coding/editTool.js

@@ -0,0 +1,154 @@
+import { promises as fs } from 'node:fs';
+import { GuardError, resolveInWorkspace, sanitizeFsError } from '../fs/workspaceGuard.js';
+import { EditError, applyPlanned, detectLineEnding, diffPreview, planEdits, restoreLineEndings, splitBom, } from './editDiff.js';
+const MAX_EDIT_FILE_SIZE_BYTES = 8 * 1024 * 1024; // matches the read tools' range-read ceiling
+/**
+ * The `edit_file` tool: exact-text replacement with a pi-contract edits[] array.
+ * All edits match against the ORIGINAL file, each must be unique and non-overlapping,
+ * and the file must have been read this session (and be unchanged since). BOM and
+ * CRLF line endings are preserved on write-back.
+ */
+export function createEditFileTool(opts) {
+    return {
+        name: 'edit_file',
+        readOnly: false,
+        description: 'Edit a single file using exact text replacement. Every edits[].old_text must match a unique, ' +
+            'non-overlapping region of the original file (match includes whitespace and newlines; never include ' +
+            'the line-number prefix from read_file output). When changing multiple separate locations in one ' +
+            'file, use ONE call with multiple entries in edits[]. Keep each old_text as small as possible while ' +
+            'still unique. The file must have been read this session before editing.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'File path relative to the workspace root.' },
+                edits: {
+                    type: 'array',
+                    description: 'One or more targeted replacements. Each is matched against the original file, not ' +
+                        'incrementally. Merge nearby changes into one edit instead of overlapping edits.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            old_text: {
+                                type: 'string',
+                                description: 'Exact existing text; must be unique in the file.',
+                            },
+                            new_text: { type: 'string', description: 'Replacement text.' },
+                        },
+                        required: ['old_text', 'new_text'],
+                    },
+                },
+            },
+            required: ['path', 'edits'],
+        },
+        async execute(args) {
+            if (typeof args.path !== 'string' || !args.path.trim()) {
+                return { error: 'Missing required "path" argument.' };
+            }
+            const edits = coerceEdits(args);
+            if (typeof edits === 'string')
+                return { error: edits };
+            try {
+                const file = await resolveInWorkspace(opts.root, args.path);
+                const stat = await fs.stat(file);
+                if (stat.isDirectory())
+                    return { error: `Is a directory, not a file: ${args.path}` };
+                if (!stat.isFile())
+                    return { error: `Not a regular file: ${args.path}` };
+                if (stat.size > MAX_EDIT_FILE_SIZE_BYTES) {
+                    return { error: `File is ${stat.size} bytes (>8MB) — too large to edit.` };
+                }
+                if (!opts.readState.has(file)) {
+                    return {
+                        error: `File has not been read yet: ${args.path}. Read it first before editing it.`,
+                    };
+                }
+                if (opts.readState.isStale(file, stat.mtimeMs)) {
+                    return {
+                        error: `File has been modified since read, either by the user or by another tool: ${args.path}. Read it again before editing it.`,
+                    };
+                }
+                const raw = await fs.readFile(file, 'utf8');
+                const { bom, text } = splitBom(raw);
+                const ending = detectLineEnding(text);
+                const content = ending === 'crlf' ? text.replace(/\r\n/g, '\n') : text;
+                // Models virtually always transcribe LF; normalize the specs the same way.
+                const specs = edits.map((e) => ({
+                    oldText: e.oldText.replace(/\r\n/g, '\n'),
+                    newText: e.newText.replace(/\r\n/g, '\n'),
+                }));
+                const planned = planEdits(content, specs, args.path);
+                const updated = applyPlanned(content, planned);
+                if (updated === content) {
+                    return {
+                        error: `No changes made to ${args.path}. The replacement produced identical content. This might indicate an issue with special characters or the text not existing as expected.`,
+                    };
+                }
+                const verdict = await opts.gate.check({
+                    kind: 'edit',
+                    path: file,
+                    preview: diffPreview(content, planned),
+                });
+                if (!verdict.ok)
+                    return { error: verdict.message };
+                // Re-stat right before writing: the approval dialog can stay open for a while,
+                // and a file changed underneath must not be clobbered with a stale base.
+                const afterStat = await fs.stat(file);
+                if (afterStat.mtimeMs !== stat.mtimeMs) {
+                    return {
+                        error: `File has been modified since read, either by the user or by another tool: ${args.path}. Read it again before editing it.`,
+                    };
+                }
+                await fs.writeFile(file, bom + restoreLineEndings(updated, ending), 'utf8');
+                const newStat = await fs.stat(file);
+                opts.readState.record(file, newStat.mtimeMs);
+                return { output: `Successfully replaced ${planned.length} block(s) in ${args.path}.` };
+            }
+            catch (err) {
+                if (err instanceof EditError)
+                    return { error: err.message };
+                if (err instanceof GuardError)
+                    return { error: err.message };
+                const message = err instanceof Error ? err.message : String(err);
+                return { error: `edit_file failed: ${sanitizeFsError(message, opts.root)}` };
+            }
+        },
+    };
+}
+/**
+ * Tolerant argument coercion (pi prepareArguments): models sometimes send `edits`
+ * as a JSON string, a single object instead of a one-element array, or legacy
+ * top-level old_text/new_text. Returns the normalized list or an error string.
+ */
+function coerceEdits(args) {
+    let rawEdits = args.edits;
+    if (typeof rawEdits === 'string') {
+        try {
+            rawEdits = JSON.parse(rawEdits);
+        }
+        catch {
+            return 'Invalid "edits": not valid JSON.';
+        }
+    }
+    if (rawEdits && !Array.isArray(rawEdits) && typeof rawEdits === 'object') {
+        rawEdits = [rawEdits];
+    }
+    const list = Array.isArray(rawEdits) ? [...rawEdits] : [];
+    if (typeof args.old_text === 'string' && typeof args.new_text === 'string') {
+        list.push({ old_text: args.old_text, new_text: args.new_text });
+    }
+    if (list.length === 0) {
+        return 'Edit tool input is invalid. edits must contain at least one replacement.';
+    }
+    const specs = [];
+    for (const item of list) {
+        const o = item;
+        const oldText = typeof o.old_text === 'string' ? o.old_text : typeof o.oldText === 'string' ? o.oldText : null;
+        const newText = typeof o.new_text === 'string' ? o.new_text : typeof o.newText === 'string' ? o.newText : null;
+        if (oldText === null || newText === null) {
+            return 'Each edit needs string old_text and new_text.';
+        }
+        specs.push({ oldText, newText });
+    }
+    return specs;
+}
+//# sourceMappingURL=editTool.js.map

package/dist/src/coding/editTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"editTool.js","sourceRoot":"","sources":["../../../src/coding/editTool.ts"],"names":[],"mappings":"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"}

package/dist/src/coding/index.d.ts

@@ -0,0 +1,25 @@
+/** Public surface of the coding tools (bash / write_file / edit_file), 2026-08-21 spec. */
+import type { ClientTool } from '../core/types.js';
+import type { BackgroundBashTasks } from './backgroundTasks.js';
+import type { PermissionGate } from './permissions.js';
+import type { ReadFileState } from './readState.js';
+export { ReadFileState } from './readState.js';
+export { CodingPermissionGate, type PermissionMode, type Approver, type ApprovalRequest, type ApprovalDecision, } from './permissionGate.js';
+export { allowAllGate, type PermissionGate, type CodingAction, type GateVerdict } from './permissions.js';
+export { buildCodingSystemMessage, loadProjectContext } from './projectContext.js';
+export { BackgroundBashTasks } from './backgroundTasks.js';
+/** The coding tool names — used by surfaces that need to filter or report on them. */
+export declare const CODING_TOOL_NAMES: ReadonlySet<string>;
+/**
+ * The three mutating tools, jailed to `root` (write/edit; bash runs with cwd=root)
+ * and gated by `gate`. Registration order = model-visible order.
+ */
+export declare function createCodingTools(opts: {
+    root: string;
+    gate: PermissionGate;
+    readState: ReadFileState;
+    /** Background bash registry (caller owns lifecycle/cleanup); absent = no background tools. */
+    background?: BackgroundBashTasks;
+    /** Test hook: where bash spill files go. */
+    spillDir?: string;
+}): ClientTool[];

package/dist/src/coding/index.js

@@ -0,0 +1,30 @@
+import { createBashTool } from './bashTool.js';
+import { createWriteFileTool } from './writeTool.js';
+import { createEditFileTool } from './editTool.js';
+import { createBashOutputTool, createBashKillTool } from './backgroundTools.js';
+export { ReadFileState } from './readState.js';
+export { CodingPermissionGate, } from './permissionGate.js';
+export { allowAllGate } from './permissions.js';
+export { buildCodingSystemMessage, loadProjectContext } from './projectContext.js';
+export { BackgroundBashTasks } from './backgroundTasks.js';
+/** The coding tool names — used by surfaces that need to filter or report on them. */
+export const CODING_TOOL_NAMES = new Set([
+    'bash',
+    'write_file',
+    'edit_file',
+    'bash_output',
+    'bash_kill',
+]);
+/**
+ * The three mutating tools, jailed to `root` (write/edit; bash runs with cwd=root)
+ * and gated by `gate`. Registration order = model-visible order.
+ */
+export function createCodingTools(opts) {
+    return [
+        createBashTool({ cwd: opts.root, gate: opts.gate, background: opts.background, spillDir: opts.spillDir }),
+        createWriteFileTool({ root: opts.root, gate: opts.gate, readState: opts.readState }),
+        createEditFileTool({ root: opts.root, gate: opts.gate, readState: opts.readState }),
+        ...(opts.background ? [createBashOutputTool(opts.background), createBashKillTool(opts.background)] : []),
+    ];
+}
+//# sourceMappingURL=index.js.map