@cspeach/cli 0.6.0

package/dist/tools/ask-question.js

@@ -0,0 +1,205 @@
+/**
+ * `ask_question` tool — the reliable replacement for text-fence widget
+ * emission. Skills call this tool whenever they need a clarifying answer
+ * from the user. The CLI pauses the agentic loop, renders the question,
+ * collects the user's input via inquirer, and returns the answer as a
+ * tool_result for the LLM's next turn.
+ *
+ * Why this exists: v0.3.1 first tried having skills emit a
+ * `cspeach-widget:question` fenced block in their text output. LLMs
+ * couldn't emit the exact fence syntax reliably; streaming chunk
+ * boundaries split the JSON unpredictably; the CLI normaliser that tried
+ * to patch all the edge cases kept introducing new ones. Tool calls are
+ * structurally reliable: the API validates the input schema, no parsing
+ * needed, no streaming ambiguity.
+ *
+ * Renders:
+ *   - kind=text: prompt for free-form answer
+ *   - kind=choice: arrow-key pick-one via inquirer select
+ *   - kind=multi: space-to-toggle via inquirer checkbox
+ *
+ * Returns JSON `{ answer, id, kind, cancelled? }` so the LLM knows what
+ * it just got back and can cross-reference the question id.
+ */
+import chalk from 'chalk';
+import { registerTool } from './index.js';
+import { input, select, checkbox } from '@inquirer/prompts';
+import { withInquirer } from '../repl/inquirer-guard.js';
+registerTool({
+    name: 'ask_question',
+    description: "Ask the user a clarifying question and get their answer. Use this for ANY user-decision point in a skill conversation — object names, design choices, approval checkpoints, etc. The CLI renders a formatted prompt, waits for the user's answer, and returns it as the tool result. Prefer this over emitting a text question — it is the only reliable mechanism for mid-turn user interaction.",
+    isMutating: false,
+    input_schema: {
+        type: 'object',
+        properties: {
+            id: {
+                type: 'string',
+                description: 'Short stable identifier for this question (e.g. "env", "names", "output-style"). Used in the tool result so you can cross-reference the answer to the question you asked.',
+            },
+            question: {
+                type: 'string',
+                description: 'The question text the user will see. Keep concise — max ~200 chars.',
+            },
+            context: {
+                type: 'string',
+                description: "Optional one-line explanation of why this matters. Shown in dim text below the question.",
+            },
+            kind: {
+                type: 'string',
+                enum: ['text', 'choice', 'multi'],
+                description: '"text" = free-form answer; "choice" = pick exactly one; "multi" = pick several.',
+            },
+            choices: {
+                type: 'array',
+                description: 'Required when kind is "choice" or "multi". Omit for "text".',
+                items: {
+                    type: 'object',
+                    properties: {
+                        value: { type: 'string', description: 'Machine value returned if the user picks this.' },
+                        label: { type: 'string', description: 'Human-readable label shown in the picker.' },
+                    },
+                    required: ['value', 'label'],
+                },
+            },
+        },
+        required: ['id', 'question', 'kind'],
+    },
+    handler: async (args, _ctx) => {
+        const id = String(args.id);
+        const question = String(args.question);
+        const context = args.context ? String(args.context) : undefined;
+        const kind = args.kind;
+        const choices = Array.isArray(args.choices)
+            ? args.choices
+            : [];
+        // 2026-05-01 redesign: when the LLM provides choices, use a real
+        // arrow-key picker (select / checkbox) instead of free-text input.
+        // The previous "always free-text, smart-resolve digits" pattern produced
+        // user mistakes (e.g. typing "2222" trying for "2") because the prompt
+        // didn't communicate that just pressing Enter on a highlighted choice
+        // works. select() is unambiguous: ↑↓ navigates, Enter picks. We still
+        // expose a "Type a custom answer" option for the LLM-allows-free-text
+        // case so flexibility isn't lost.
+        console.log('');
+        console.log(chalk.bold(question));
+        if (context)
+            console.log(chalk.dim(context));
+        console.log('');
+        let answer;
+        try {
+            if (kind === 'choice' && choices.length > 0) {
+                // Arrow-key pick-one. Always include a "type a custom answer" escape
+                // so the LLM's free-form-allowed contract still holds.
+                const CUSTOM = '__cspeach_custom__';
+                const picked = await withInquirer(() => select({
+                    message: 'Pick an answer:',
+                    choices: [
+                        ...choices.map((c) => ({ value: c.value, name: c.label })),
+                        { value: CUSTOM, name: chalk.dim('(type a custom answer)') },
+                    ],
+                }));
+                if (picked === CUSTOM) {
+                    const raw = await withInquirer(() => input({ message: 'Your answer:' }));
+                    answer = raw.trim();
+                }
+                else {
+                    answer = picked;
+                }
+            }
+            else if (kind === 'multi' && choices.length > 0) {
+                // Space-to-toggle multi-pick. checkbox returns string[] of values.
+                const picked = await withInquirer(() => checkbox({
+                    message: 'Pick one or more (space to toggle, enter to confirm):',
+                    choices: choices.map((c) => ({ value: c.value, name: c.label })),
+                }));
+                answer = picked.join(',');
+            }
+            else {
+                // Free-text. kind === 'text' or no choices supplied.
+                const raw = await withInquirer(() => input({ message: 'Your answer:' }));
+                answer = raw.trim();
+            }
+        }
+        catch (err) {
+            const name = err?.name;
+            if (name === 'ExitPromptError') {
+                return {
+                    content: JSON.stringify({ id, kind, answer: null, cancelled: true }),
+                };
+            }
+            throw err;
+        }
+        if (answer.length === 0) {
+            return {
+                content: JSON.stringify({ id, kind, answer: null, cancelled: true }),
+            };
+        }
+        console.log(chalk.dim(`  → ${answer}`));
+        return {
+            content: JSON.stringify({ id, kind, answer }),
+        };
+    },
+});
+/**
+ * Resolve a single typed answer to either a choice value or raw text.
+ * Matches (in order):
+ *   1. A 1-based index into choices (e.g. "2" → choices[1].value)
+ *   2. An exact (case-insensitive) match against choice values or labels
+ *   3. Otherwise → the raw input as-is (free text)
+ */
+function resolveSingleAnswer(raw, choices) {
+    const asInt = Number.parseInt(raw, 10);
+    if (Number.isFinite(asInt) && asInt >= 1 && asInt <= choices.length && String(asInt) === raw) {
+        return choices[asInt - 1].value;
+    }
+    const lower = raw.toLowerCase();
+    for (const c of choices) {
+        if (c.value.toLowerCase() === lower || c.label.toLowerCase() === lower)
+            return c.value;
+    }
+    return raw;
+}
+/**
+ * Resolve a multi-answer input. Accepts:
+ *   - "1,3,5" or "1 3 5" — comma/space-separated indices → comma-joined values
+ *   - "vkorg,erdat" — value/label list → comma-joined values
+ *   - "all" — all choice values
+ *   - "none" — empty string
+ *   - anything else → free text as-is
+ */
+function resolveMultiAnswer(raw, choices) {
+    const lower = raw.trim().toLowerCase();
+    if (lower === 'all')
+        return choices.map((c) => c.value).join(',');
+    if (lower === 'none' || lower === '')
+        return '';
+    // Try comma/space split
+    const parts = raw.split(/[,\s]+/).map((p) => p.trim()).filter(Boolean);
+    if (parts.length === 0)
+        return raw;
+    const resolved = [];
+    let allMatched = true;
+    for (const part of parts) {
+        const asInt = Number.parseInt(part, 10);
+        if (Number.isFinite(asInt) &&
+            asInt >= 1 &&
+            asInt <= choices.length &&
+            String(asInt) === part) {
+            resolved.push(choices[asInt - 1].value);
+            continue;
+        }
+        const partLower = part.toLowerCase();
+        const hit = choices.find((c) => c.value.toLowerCase() === partLower || c.label.toLowerCase() === partLower);
+        if (hit) {
+            resolved.push(hit.value);
+        }
+        else {
+            allMatched = false;
+            break;
+        }
+    }
+    if (allMatched && resolved.length > 0)
+        return resolved.join(',');
+    // Fell back — return raw text
+    return raw;
+}

package/dist/tools/dispatch-skill.js

@@ -0,0 +1,81 @@
+/**
+ * dispatch_skill — auto-route the next user submission to a slash command
+ * the user already explicitly approved via an inquirer picker.
+ *
+ * UX problem this fixes: when /abap-generate detects a RAP-shaped design
+ * and asks "Switch to /abap-rap?" via ask_question, the user picks
+ * "Switch" — and was then told "Type `/abap-rap --from @<file>` at the
+ * next prompt". Re-typing what they already approved is busywork. The
+ * picker IS the consent.
+ *
+ * Contract:
+ *   - The skill calls dispatch_skill ONLY after the user has explicitly
+ *     consented via an inquirer prompt (ask_question, picker, etc.).
+ *     Never auto-dispatch from prose / TL;DR alone — that's still the
+ *     user's keypress to make.
+ *   - The command argument MUST start with a known slash route. Free
+ *     text without a leading `/` is rejected.
+ *   - Set the slot via ctx.pendingDispatch.set(command). repl.tsx reads
+ *     it after runTurn and routes as the next submission.
+ *   - Skill ends the turn naturally after this tool call. Do not also
+ *     emit a "Type X at the next prompt" hint — the dispatch supersedes it.
+ *
+ * The harness clears pendingDispatch at the start of every consume cycle,
+ * so a stale dispatch from a prior turn never re-fires.
+ */
+import { registerTool } from './index.js';
+registerTool({
+    name: 'dispatch_skill',
+    description: 'Queue the next user submission to a slash command the user already explicitly approved via an inquirer picker. Use this in place of telling the user "Type X at the next prompt" — re-typing what they already picked is friction. Only call this AFTER an explicit user consent (ask_question pick, picker confirmation, etc.); never from prose or a one-line suggestion. The command must start with a known slash route (e.g. "/abap-rap --from @<file>"). After this tool returns, end the turn — do not also print a continuation hint.',
+    isMutating: false,
+    input_schema: {
+        type: 'object',
+        properties: {
+            command: {
+                type: 'string',
+                description: 'Full slash command including arguments. Must start with `/`. Example: `/abap-rap --from @order-approval-system-design-2924-v1.cspeach.json`.',
+            },
+        },
+        required: ['command'],
+    },
+    handler: async (args, ctx) => {
+        const command = typeof args.command === 'string' ? args.command.trim() : '';
+        if (command.length === 0) {
+            return {
+                is_error: true,
+                content: JSON.stringify({
+                    error: 'DISPATCH_INVALID',
+                    reason: 'command argument is required and must be a non-empty string',
+                }),
+            };
+        }
+        if (!command.startsWith('/')) {
+            return {
+                is_error: true,
+                content: JSON.stringify({
+                    error: 'DISPATCH_INVALID',
+                    reason: `command must start with "/" — got "${command.slice(0, 32)}…"`,
+                }),
+            };
+        }
+        if (!ctx.pendingDispatch) {
+            // Non-REPL path (one-shot, tests). Tell the model the dispatch
+            // can't take effect here so it falls back to a continuation hint.
+            return {
+                is_error: true,
+                content: JSON.stringify({
+                    error: 'DISPATCH_UNSUPPORTED',
+                    reason: 'pendingDispatch not registered in this context (one-shot or test mode); use a continuation hint instead',
+                }),
+            };
+        }
+        ctx.pendingDispatch.set(command);
+        return {
+            content: JSON.stringify({
+                ok: true,
+                queued: command,
+                note: 'The next user submission will run this command automatically. End the turn — do not print a "Type X" hint.',
+            }),
+        };
+    },
+});

package/dist/tools/filesystem/file-edit.js

@@ -0,0 +1,140 @@
+/**
+ * file_edit — Phase 3 filesystem tool.
+ *
+ * Exact-match string replacement in a project file. Errors if old_string
+ * is not found, or if it appears multiple times and replace_all is false.
+ * First mutating Phase 3 tool (isMutating: true).
+ *
+ * Write is atomic: content goes to <path>.tmp then fs.rename swaps it in.
+ * Line endings are preserved — Node reads and writes UTF-8 with no
+ * normalization, so whatever endings the file had on disk are kept.
+ *
+ * Flag-gated: invisible to listTools() unless CSPEACH_TOOL_FILE_EDIT=on.
+ */
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { registerTool } from '../index.js';
+import { resolveSafePath, assertRealPathContained, PathOutsideRootError, BLOCKED_PREFIXES, isDenylistedPath, } from '../_filesystem-shared.js';
+export async function fileEditHandler(args, ctx) {
+    // 1. Validate args before any IO
+    if (args.old_string === args.new_string) {
+        return {
+            content: 'error: old_string and new_string are identical — no-op edit refused',
+            is_error: true,
+        };
+    }
+    // 2. Path containment — sync phase (pure string math)
+    let abs;
+    try {
+        abs = resolveSafePath(ctx.cwd, args.path);
+    }
+    catch (err) {
+        if (err instanceof PathOutsideRootError) {
+            return { content: `error: ${err.message}`, is_error: true };
+        }
+        return { content: `error: ${err instanceof Error ? err.message : String(err)}`, is_error: true };
+    }
+    // 3. Path containment — async phase (follows symlinks)
+    let realAbs;
+    try {
+        realAbs = await assertRealPathContained(abs, ctx.cwd);
+    }
+    catch (err) {
+        if (err instanceof PathOutsideRootError) {
+            return { content: `error: ${err.message} (after symlink resolution)`, is_error: true };
+        }
+        if (err.code === 'ENOENT') {
+            return { content: 'error: file not found', is_error: true };
+        }
+        return { content: `error: ${err instanceof Error ? err.message : String(err)}`, is_error: true };
+    }
+    // 4. Denylist check: refuse sensitive in-root paths
+    const denylist = isDenylistedPath(realAbs, ctx.cwd);
+    if (denylist.blocked) {
+        return {
+            content: `error: refusing to edit sensitive path "${denylist.relFromRoot}" (denylist: ${BLOCKED_PREFIXES.join(', ')})`,
+            is_error: true,
+        };
+    }
+    // 5. Read the file
+    let content;
+    try {
+        content = await fs.readFile(realAbs, 'utf-8');
+    }
+    catch (err) {
+        return { content: `error: ${err.code === 'ENOENT' ? 'file not found' : err.message}`, is_error: true };
+    }
+    // 6. Count occurrences of old_string
+    let count = 0;
+    let searchFrom = 0;
+    while (true) {
+        const idx = content.indexOf(args.old_string, searchFrom);
+        if (idx === -1)
+            break;
+        count++;
+        searchFrom = idx + args.old_string.length;
+    }
+    if (count === 0) {
+        return {
+            content: `error: old_string not found in "${args.path}"`,
+            is_error: true,
+        };
+    }
+    if (count > 1 && !args.replace_all) {
+        return {
+            content: `error: old_string matches ${count} times in "${args.path}"; ` +
+                `pass replace_all: true to replace all or make old_string more specific`,
+            is_error: true,
+        };
+    }
+    // 7. Perform replacement
+    const newContent = args.replace_all
+        ? content.replaceAll(args.old_string, args.new_string)
+        : content.replace(args.old_string, args.new_string);
+    const replacementCount = args.replace_all ? count : 1;
+    // 8. Atomic write: tmp file then rename
+    const tmpPath = realAbs + '.tmp';
+    try {
+        await fs.writeFile(tmpPath, newContent, 'utf-8');
+        await fs.rename(tmpPath, realAbs);
+    }
+    catch (err) {
+        // Best-effort cleanup of tmp file on failure
+        await fs.unlink(tmpPath).catch(() => undefined);
+        return { content: `error: write failed — ${err.message}`, is_error: true };
+    }
+    const noun = replacementCount === 1 ? 'replacement' : 'replacements';
+    const relPath = path.relative(path.resolve(ctx.cwd), realAbs).replace(/\\/g, '/');
+    return { content: `edited ${relPath} (${replacementCount} ${noun})` };
+}
+registerTool({
+    name: 'file_edit',
+    description: 'Exact-match string replacement in a project file. ' +
+        'Errors if old_string is not found, or if it matches multiple times without replace_all: true.',
+    isMutating: true,
+    category: 'filesystem',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: 'Path relative to the project root, or an absolute path inside the project.',
+            },
+            old_string: {
+                type: 'string',
+                description: 'The exact string to find and replace.',
+            },
+            new_string: {
+                type: 'string',
+                description: 'The replacement string.',
+            },
+            replace_all: {
+                type: 'boolean',
+                description: 'When true, replace every occurrence. Default false (errors if more than one match).',
+            },
+        },
+        required: ['path', 'old_string', 'new_string'],
+    },
+    handler: fileEditHandler,
+});

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

@@ -0,0 +1,89 @@
+/**
+ * file_read — Phase 3 filesystem tool.
+ *
+ * Reads a file from the project and returns content with cat -n style
+ * line numbers (matching the existing CSPeach Read tool convention).
+ * Hard cap at 2000 lines per call; offset + limit support windowed
+ * reads of large files. Path containment via resolveSafePath.
+ *
+ * Flag-gated: invisible to listTools() unless CSPEACH_TOOL_FILE_READ=on.
+ */
+import { promises as fs } from 'node:fs';
+import { registerTool } from '../index.js';
+import { resolveSafePath, assertRealPathContained, PathOutsideRootError, BLOCKED_PREFIXES, isDenylistedPath } from '../_filesystem-shared.js';
+const MAX_LINES = 2000;
+export async function fileReadHandler(args, ctx) {
+    // Validate offset and limit BEFORE clamping
+    if (args.offset !== undefined && args.offset < 0) {
+        return { content: `error: offset must be non-negative (got ${args.offset})`, is_error: true };
+    }
+    if (args.limit !== undefined && args.limit < 1) {
+        return { content: `error: limit must be a positive integer (got ${args.limit})`, is_error: true };
+    }
+    let abs;
+    try {
+        abs = resolveSafePath(ctx.cwd, args.path);
+    }
+    catch (err) {
+        if (err instanceof PathOutsideRootError) {
+            return { content: `error: ${err.message}`, is_error: true };
+        }
+        return { content: `error: ${err instanceof Error ? err.message : String(err)}`, is_error: true };
+    }
+    let realAbs;
+    try {
+        realAbs = await assertRealPathContained(abs, ctx.cwd);
+    }
+    catch (err) {
+        if (err instanceof PathOutsideRootError) {
+            return { content: `error: ${err.message} (after symlink resolution)`, is_error: true };
+        }
+        if (err.code === 'ENOENT') {
+            return { content: 'error: file not found', is_error: true };
+        }
+        return { content: `error: ${err instanceof Error ? err.message : String(err)}`, is_error: true };
+    }
+    // Denylist check: refuse sensitive in-root paths
+    const denylist = isDenylistedPath(realAbs, ctx.cwd);
+    if (denylist.blocked) {
+        return {
+            content: `error: refusing to read sensitive path "${denylist.relFromRoot}" (denylist: ${BLOCKED_PREFIXES.join(', ')})`,
+            is_error: true,
+        };
+    }
+    let raw;
+    try {
+        raw = await fs.readFile(realAbs, 'utf-8');
+    }
+    catch (err) {
+        return { content: `error: ${err.code === 'ENOENT' ? 'file not found' : err.message}`, is_error: true };
+    }
+    // Strip trailing newline before split to avoid phantom blank last line
+    const allLines = raw.replace(/\n$/, '').split('\n');
+    const offset = Math.max(0, args.offset ?? 0);
+    const limit = Math.min(args.limit ?? MAX_LINES, MAX_LINES);
+    const window = allLines.slice(offset, offset + limit);
+    const numbered = window.map((line, i) => `${offset + i + 1}\t${line}`).join('\n');
+    const truncated = allLines.length > offset + window.length;
+    const trailer = truncated
+        ? `\n... (truncated, ${allLines.length - (offset + window.length)} more lines — re-read with offset=${offset + window.length})`
+        : '';
+    return { content: numbered + trailer };
+}
+registerTool({
+    name: 'file_read',
+    description: 'Read a file from the project. Returns content with line numbers. Optional offset + limit for windowed reads of large files.',
+    isMutating: false,
+    category: 'filesystem',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            path: { type: 'string', description: 'Path relative to the project root, or an absolute path inside the project.' },
+            offset: { type: 'number', description: 'Optional 0-based line offset.' },
+            limit: { type: 'number', description: 'Optional max lines to return (cap 2000).' },
+        },
+        required: ['path'],
+    },
+    handler: fileReadHandler,
+});

package/dist/tools/filesystem/file-write.js

@@ -0,0 +1,128 @@
+/**
+ * file_write — Phase 3 filesystem tool.
+ *
+ * Creates a new file or overwrites an existing one. Unlike file_edit which
+ * requires the file to exist, file_write is the canonical "put this content
+ * at this path" primitive. Parent directories are auto-created so the model
+ * can write to fresh subdirectories without a separate mkdir step.
+ *
+ * Write is atomic: content goes to <path>.tmp then fs.rename swaps it in so
+ * a crash mid-write never leaves a partial file at the target path.
+ *
+ * Path containment via resolveSafePath + assertRealPathContained. For
+ * non-existent target files (the common create case), assertRealPathContained
+ * would throw ENOENT because fs.realpath requires the path to exist. In that
+ * case we fall back to verifying the parent directory is contained instead,
+ * using the original abs path (from resolveSafePath) as the write target.
+ *
+ * Flag-gated: invisible to listTools() unless CSPEACH_TOOL_FILE_WRITE=on.
+ */
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { registerTool } from '../index.js';
+import { resolveSafePath, assertRealPathContained, PathOutsideRootError, BLOCKED_PREFIXES, isDenylistedPath, } from '../_filesystem-shared.js';
+export async function fileWriteHandler(args, ctx) {
+    // 1. Path containment — sync phase (pure string math, catches .. traversals)
+    let abs;
+    try {
+        abs = resolveSafePath(ctx.cwd, args.path);
+    }
+    catch (err) {
+        if (err instanceof PathOutsideRootError) {
+            return { content: `error: ${err.message}`, is_error: true };
+        }
+        return { content: `error: ${err instanceof Error ? err.message : String(err)}`, is_error: true };
+    }
+    // 2. Path containment — async phase (follows symlinks to catch symlink escapes).
+    //    For non-existent files (the common create case), fs.realpath throws ENOENT.
+    //    In that case, verify the parent directory is contained instead.
+    let target;
+    try {
+        target = await assertRealPathContained(abs, ctx.cwd);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            // Target file doesn't exist yet (create case) — verify parent is contained.
+            const parent = path.dirname(abs);
+            try {
+                await assertRealPathContained(parent, ctx.cwd);
+            }
+            catch (parentErr) {
+                if (parentErr.code === 'ENOENT') {
+                    // Parent doesn't exist either (will be mkdir -p'd) — verify via string math.
+                    const relFromRoot = path.relative(path.resolve(ctx.cwd), parent);
+                    if (relFromRoot.startsWith('..') || path.isAbsolute(relFromRoot)) {
+                        return { content: 'error: parent directory escapes project root', is_error: true };
+                    }
+                    // Parent is fine — use the original abs as write target.
+                }
+                else if (parentErr instanceof PathOutsideRootError) {
+                    return { content: `error: ${parentErr.message}`, is_error: true };
+                }
+                else {
+                    return { content: `error: ${parentErr.message}`, is_error: true };
+                }
+            }
+            // Use the original abs path (resolveSafePath result) as write target.
+            target = abs;
+        }
+        else if (err instanceof PathOutsideRootError) {
+            return { content: `error: ${err.message} (after symlink resolution)`, is_error: true };
+        }
+        else {
+            return { content: `error: ${err instanceof Error ? err.message : String(err)}`, is_error: true };
+        }
+    }
+    // 3. Denylist check: refuse sensitive in-root paths
+    const denylist = isDenylistedPath(target, ctx.cwd);
+    if (denylist.blocked) {
+        return {
+            content: `error: refusing to write sensitive path "${denylist.relFromRoot}" (denylist: ${BLOCKED_PREFIXES.join(', ')})`,
+            is_error: true,
+        };
+    }
+    // 4. Ensure parent directory exists (no-op if it already does)
+    try {
+        await fs.mkdir(path.dirname(target), { recursive: true });
+    }
+    catch (err) {
+        return { content: `error: could not create parent directory — ${err.message}`, is_error: true };
+    }
+    // 5. Atomic write: tmp file then rename
+    const tmpPath = target + '.tmp';
+    try {
+        await fs.writeFile(tmpPath, args.content, 'utf-8');
+        await fs.rename(tmpPath, target);
+    }
+    catch (err) {
+        // Best-effort cleanup of tmp file on failure
+        await fs.unlink(tmpPath).catch(() => undefined);
+        return { content: `error: write failed — ${err.message}`, is_error: true };
+    }
+    const relPath = path.relative(path.resolve(ctx.cwd), target).replace(/\\/g, '/');
+    const bytes = Buffer.byteLength(args.content, 'utf-8');
+    return { content: `wrote ${relPath} (${bytes} bytes)` };
+}
+registerTool({
+    name: 'file_write',
+    description: 'Create a new file or overwrite an existing one with the given content. ' +
+        'Parent directories are created automatically. Uses an atomic write (tmp + rename).',
+    isMutating: true,
+    category: 'filesystem',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: 'Path relative to the project root, or an absolute path inside the project.',
+            },
+            content: {
+                type: 'string',
+                description: 'The full content to write to the file.',
+            },
+        },
+        required: ['path', 'content'],
+    },
+    handler: fileWriteHandler,
+});