@yagni-app/code-staging 1.1.2-staging.1368.1 → 1.1.2-staging.1370.1

package/dist/extension/branding.d.ts

@@ -72,6 +72,19 @@ export declare const TICKET_IMAGE_RULE: string;
  * the standalone word "pi", must not open with a `- ` bullet line, no emojis.
  */
 export declare const GITHUB_OPERATIONS: string;
+/**
+ * File-tool steering: prefer the first-class write/edit tools over bash file
+ * writes, one write call per file instead of a heredoc batch, and never create
+ * documentation files unless asked. Mirrors Claude Code's "Using your tools"
+ * preference block plus its write-tool description guidance. The observed
+ * bash — the model traded tool-call count against the known-safe path — so
+ * the multi-file line steers that incentive back to one write call per file.
+ *
+ * Content constraints (parity with {@link GITHUB_OPERATIONS}): must not
+ * contain the standalone word "pi", must not open with a `- ` bullet line,
+ * no emojis, no ticket ids.
+ */
+export declare const FILE_TOOL_STEERING: string;
 /**
  * The injected-reminder framing (YAG-574, Change A prerequisite). Claude Code
  * carries this exact sentence in every system prompt so its whole reminder
@@ -147,6 +160,16 @@ export interface BrandSystemPromptOptions {
      * attribution talk at all.
      */
     attributionSection?: string | null;
+    /**
+     * Inject the file-tool steering section (write over bash writes, edit for
+     * modifications). Set ONLY where the file-tool guards it promises are
+     * actually registered — the condensed-tools registration in index.ts. An
+     * opt-in flag rather than a section string because the mismatch it guards
+     * against (a prompt saying "this tool will fail without a read" on a
+     * surface with no guard — eval mode, desktop, classic rows) is an
+     * all-or-nothing per-surface call, not user policy.
+     */
+    fileToolSteering?: boolean;
 }
 /**
  * Rebrand pi's assembled system prompt as YAGNI Code's, and optionally inject a

package/dist/extension/branding.js

@@ -155,6 +155,35 @@ export const GITHUB_OPERATIONS = "## GitHub Operations\n" +
     "multi-paragraph.";
 /** Stable header that starts the GitHub operations section (idempotency anchor). */
 const GITHUB_OPERATIONS_HEADER = "## GitHub Operations";
+/**
+ * File-tool steering: prefer the first-class write/edit tools over bash file
+ * writes, one write call per file instead of a heredoc batch, and never create
+ * documentation files unless asked. Mirrors Claude Code's "Using your tools"
+ * preference block plus its write-tool description guidance. The observed
+ * bash — the model traded tool-call count against the known-safe path — so
+ * the multi-file line steers that incentive back to one write call per file.
+ *
+ * Content constraints (parity with {@link GITHUB_OPERATIONS}): must not
+ * contain the standalone word "pi", must not open with a `- ` bullet line,
+ * no emojis, no ticket ids.
+ */
+export const FILE_TOOL_STEERING = "## File tools over bash file writes\n" +
+    "\n" +
+    "Prefer the first-class file tools over bash for every file change:\n" +
+    "\n" +
+    "* Use `write` to create files, never `cat >` with a heredoc or `echo >`\n" +
+    "  redirection. When several files must be written, issue one `write` call per\n" +
+    "  file rather than batching them into a single bash heredoc.\n" +
+    "* Use `edit` to modify existing files — `write` is for new files and complete\n" +
+    "  rewrites, not for changes to files you have read.\n" +
+    "* NEVER create documentation files (*.md) or README files unless the user\n" +
+    "  explicitly asks for one.\n" +
+    "\n" +
+    "Reserve bash for system commands and terminal operations that require shell\n" +
+    "execution. Using the file tools lets the user review your work and keeps the\n" +
+    "permission path silent; a bash write escapes both.";
+/** Stable header that starts the file-tool steering section (idempotency anchor). */
+const FILE_TOOL_STEERING_HEADER = "## File tools over bash file writes";
 /**
  * The injected-reminder framing (YAG-574, Change A prerequisite). Claude Code
  * carries this exact sentence in every system prompt so its whole reminder
@@ -345,6 +374,13 @@ export function brandSystemPrompt(original, opts = {}) {
     if (!s.includes(GITHUB_OPERATIONS_HEADER)) {
         s = `${s}\n\n${GITHUB_OPERATIONS}`;
     }
+    // 5b2b. File-tool steering — same standing-directive placement and
+    // idempotency shape as GitHub operations (guarded by its stable header),
+    // but gated on the caller confirming the guards it promises are live
+    // (see fileToolSteering's doc).
+    if (opts.fileToolSteering && !s.includes(FILE_TOOL_STEERING_HEADER)) {
+        s = `${s}\n\n${FILE_TOOL_STEERING}`;
+    }
     // 5b3. Commit / PR attribution — a standing directive next to the GitHub
     // operations it qualifies (same placement, same idempotency shape, keyed on
     // the section's stable first line). Settings-driven: the section is absent

package/dist/extension/condensedTools.js

@@ -28,6 +28,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { createBashToolDefinition, createEditToolDefinition, createFindToolDefinition, createGrepToolDefinition, createLsToolDefinition, createReadToolDefinition, createWriteToolDefinition, getAgentDir, getLanguageFromPath, highlightCode, renderDiff, SettingsManager, } from "@earendil-works/pi-coding-agent";
 import { Container, Text } from "@earendil-works/pi-tui";
+import { ReadStateTracker, READ_FIRST_ERROR, readIsPartial, readTextOf, STALE_ERROR } from "./fileGuards.js";
 import { isQuiet, kindForTool, ToolRunTracker } from "./toolRuns.js";
 /** Lines of write content shown collapsed (mirrors Claude Code's preview). */
 export const WRITE_PREVIEW_LINES = 8;
@@ -55,6 +56,19 @@ const TITLE_BY_NAME = {
     find: "Find",
     ls: "List",
 };
+/** Claude Code's write-tool description guidance, adapted to our arg names. */
+const WRITE_DESCRIPTION = "Write content to a file. Creates the file if it doesn't exist, overwrites if it does. " +
+    "Automatically creates parent directories.\n" +
+    "Usage:\n" +
+    "- If this is an existing file, you MUST use the read tool first to read the file's contents. " +
+    "This tool will fail if you did not read the file first.\n" +
+    "- Prefer the edit tool for modifying existing files — it only sends the diff. Only use this tool " +
+    "to create new files or for complete rewrites.\n" +
+    "- NEVER create documentation files (*.md) or README files unless explicitly requested by the user.";
+/** Claude Code's edit-tool pre-read instruction, adapted. */
+const EDIT_DESCRIPTION_APPENDIX = "\nUsage:\n" +
+    "- You must use the read tool at least once in the conversation before editing. This tool will " +
+    "error if you attempt an edit without reading the file.";
 /** Collapse whitespace and clip to `max`, appending an ellipsis when cut. */
 function clip(text, max) {
     const collapsed = text.replace(/\s+/g, " ").trim();
@@ -257,6 +271,10 @@ function textOf(result) {
 function hasImages(result) {
     return (result?.content ?? []).some((c) => c.type === "image");
 }
+/** A failed tool result carries no fresh state to record. */
+function isErrorResult(result) {
+    return result?.isError === true;
+}
 function empty() {
     return new Container();
 }
@@ -318,6 +336,11 @@ export function registerCondensedTools(pi, deps = {}) {
         return defs;
     };
     definitionsByCwd.set(registrationCwd, buildDefinitions(registrationCwd));
+    // Read-first + staleness guards (Claude Code's FileWriteTool/FileEditTool
+    // parity): one session-scoped tracker records what `read` last returned, and
+    // write/edit refuse to overwrite an existing unread or changed file. The
+    // scratchpad is exempt so permission-free scratchpad writes stay silent.
+    const readState = new ReadStateTracker(deps.scratchpadDir);
     for (const name of BUILTIN_NAMES) {
         const base = definitionsFor(registrationCwd)[name];
         const kind = kindForTool(name);
@@ -333,10 +356,48 @@ export function registerCondensedTools(pi, deps = {}) {
         };
         pi.registerTool({
             ...base,
+            ...(name === "write" ? { description: WRITE_DESCRIPTION } : {}),
+            ...(name === "edit" ? { description: `${base.description}${EDIT_DESCRIPTION_APPENDIX}` } : {}),
             renderShell: "self",
-            execute(toolCallId, params, signal, onUpdate, ctx) {
+            async execute(toolCallId, params, signal, onUpdate, ctx) {
                 const cwd = ctx?.cwd ?? registrationCwd;
-                return definitionsFor(cwd)[name].execute(toolCallId, params, signal, onUpdate, ctx);
+                const args = params;
+                const target = typeof args?.path === "string" ? args.path : undefined;
+                // write/edit: refuse unread or stale overwrites, then refresh the
+                // read state so consecutive writes/edits keep working. A guard fs
+                // error that is not one of the two refusals fails OPEN (delegate);
+                // pi's own execute produces the error the model would have seen.
+                if (target && (name === "write" || name === "edit")) {
+                    try {
+                        await readState.assertFreshRead(target, cwd);
+                    }
+                    catch (error) {
+                        if (error instanceof Error && (error.message === READ_FIRST_ERROR || error.message === STALE_ERROR)) {
+                            throw error;
+                        }
+                        // Not a refusal — delegate and let pi's execute handle it.
+                    }
+                }
+                const result = await definitionsFor(cwd)[name].execute(toolCallId, params, signal, onUpdate, ctx);
+                // read: record what the model saw. write/edit: the just-written
+                // state is the fresh truth. AWAITED, not fire-and-forget — a follow-up
+                // write/edit in the same burst must not race a pending refresh and
+                // get refused as stale (Claude Code updates readFileState before the
+                // tool call returns; the captures are one stat and at most one small
+                // read, and each fails soft internally). A FAILED read records
+                // nothing — its content is error text, not the file — and must not
+                // clobber a prior good record of the same path.
+                if (name === "read" && target && !isErrorResult(result)) {
+                    const partial = readIsPartial({ path: args.path, offset: args.offset, limit: args.limit }, result.details ?? undefined);
+                    await readState.recordRead(target, cwd, readTextOf(result), partial);
+                }
+                else if (name === "write" && target && typeof args.content === "string" && !isErrorResult(result)) {
+                    await readState.recordWrite(target, cwd, args.content);
+                }
+                else if (name === "edit" && target && !isErrorResult(result)) {
+                    await readState.refreshFromDisk(target, cwd);
+                }
+                return result;
             },
             renderCall(args, theme, context) {
                 const slice = context;

package/dist/extension/fileGuards.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Read-first + staleness guards for the `write` and `edit` file tools —
+ * Claude Code's FileWriteTool/FileEditTool safety level, adapted to pi's
+ * tool shapes.
+ *
+ * A session-scoped `ReadStateTracker` records what the `read` tool last
+ * returned per canonical path (fs.realpath where it exists, path.resolve
+ * otherwise). `write`/`edit` refuse to overwrite an existing file the
+ * model has not read in this session, and refuse again when the file
+ * changed on disk since that read (mtime, with a content-compare fallback
+ * so a spurious timestamp bump — cloud sync, antivirus, `utimes` noise —
+ * does not produce a false refusal on a full read). New-file creates and
+ * partial reads follow Claude Code exactly: a create needs no prior read;
+ * an offset/limit or truncated read does NOT satisfy the read-first
+ * requirement (`isPartialView`).
+ *
+ * Fail-open contract: any guard-internal filesystem error that is not one
+ * of the two refusals (EACCES, EMFILE, a racing delete, ...) delegates
+ * straight to the underlying pi execute, which produces its own error.
+ * The guard must never invent a refusal pi wouldn't.
+ */
+/** Claude Code's exact refusal, errorCode 2. */
+export declare const READ_FIRST_ERROR = "File has not been read yet. Read it first before writing to it.";
+/** Claude Code's exact refusal, errorCode 3. */
+export declare const STALE_ERROR = "File has been modified since read, either by the user or by a linter. Read it again before attempting to write it.";
+/** A read result's details slice, as pi's read tool emits it. */
+interface ReadDetails {
+    truncation?: {
+        truncated?: boolean;
+    };
+}
+export interface ReadArgs {
+    path?: unknown;
+    offset?: unknown;
+    limit?: unknown;
+}
+/** Whether the read call viewed only a slice of the file. */
+export declare function readIsPartial(args: ReadArgs, details: ReadDetails | undefined): boolean;
+/** The text content of a read tool result, empty when it carries none. */
+export declare function readTextOf(result: {
+    content?: Array<{
+        type: string;
+        text?: string;
+    }>;
+} | undefined): string;
+/**
+ * Session read state. One instance per registration (created by
+ * registerCondensedTools), so driver, `/go` stage children, and subagents
+ * each track their own session's reads — matching Claude Code's
+ * per-conversation readFileState.
+ */
+export declare class ReadStateTracker {
+    /** Session scratchpad dir; paths under it are exempt from the guards. */
+    private readonly scratchpadDir;
+    /** Stat/read seams for tests. */
+    private readonly io;
+    private reads;
+    constructor(
+    /** Session scratchpad dir; paths under it are exempt from the guards. */
+    scratchpadDir: string | undefined, 
+    /** Stat/read seams for tests. */
+    io?: {
+        stat?: (p: string) => Promise<{
+            mtimeMs: number;
+        }>;
+        readFile?: (p: string) => Promise<string>;
+    });
+    /** Record a successful read of `rawPath` (resolved against `cwd`). */
+    recordRead(rawPath: string, cwd: string, text: string, partial: boolean): Promise<void>;
+    /** Record a successful write (the written content is the fresh truth). */
+    recordWrite(rawPath: string, cwd: string, content: string): Promise<void>;
+    /** Refresh a record from disk after a successful edit (content unknown to us). */
+    refreshFromDisk(rawPath: string, cwd: string): Promise<void>;
+    private capture;
+    /**
+     * Throw one of the two refusals when the write/edit must not proceed.
+     * Resolves (returns) when the overwrite may continue; rethrows any fs
+     * error it did not classify, so the wrapper can fail open.
+     */
+    assertFreshRead(rawPath: string, cwd: string): Promise<void>;
+    private isInside;
+}
+export {};
+//# sourceMappingURL=fileGuards.d.ts.map

package/dist/extension/fileGuards.js

@@ -0,0 +1,210 @@
+/**
+ * Read-first + staleness guards for the `write` and `edit` file tools —
+ * Claude Code's FileWriteTool/FileEditTool safety level, adapted to pi's
+ * tool shapes.
+ *
+ * A session-scoped `ReadStateTracker` records what the `read` tool last
+ * returned per canonical path (fs.realpath where it exists, path.resolve
+ * otherwise). `write`/`edit` refuse to overwrite an existing file the
+ * model has not read in this session, and refuse again when the file
+ * changed on disk since that read (mtime, with a content-compare fallback
+ * so a spurious timestamp bump — cloud sync, antivirus, `utimes` noise —
+ * does not produce a false refusal on a full read). New-file creates and
+ * partial reads follow Claude Code exactly: a create needs no prior read;
+ * an offset/limit or truncated read does NOT satisfy the read-first
+ * requirement (`isPartialView`).
+ *
+ * Fail-open contract: any guard-internal filesystem error that is not one
+ * of the two refusals (EACCES, EMFILE, a racing delete, ...) delegates
+ * straight to the underlying pi execute, which produces its own error.
+ * The guard must never invent a refusal pi wouldn't.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { logEvent } from "./errorSink.js";
+/** Claude Code's exact refusal, errorCode 2. */
+export const READ_FIRST_ERROR = "File has not been read yet. Read it first before writing to it.";
+/** Claude Code's exact refusal, errorCode 3. */
+export const STALE_ERROR = "File has been modified since read, either by the user or by a linter. Read it again before attempting to write it.";
+/** Whether the read call viewed only a slice of the file. */
+export function readIsPartial(args, details) {
+    if (args.offset !== undefined || args.limit !== undefined)
+        return true;
+    return details?.truncation?.truncated === true;
+}
+/** The text content of a read tool result, empty when it carries none. */
+export function readTextOf(result) {
+    return (result?.content ?? [])
+        .filter((c) => c.type === "text" && typeof c.text === "string")
+        .map((c) => c.text)
+        .join("\n");
+}
+/** Canonical key: fs.realpath where the entry exists (symlinks resolved,
+ * so two spellings of one file share a record and a symlink cannot smuggle
+ * the scratchpad exemption to an outside file). When the entry does not
+ * exist: a DANGLING symlink keys as its eventual target (a link inside a
+ * privileged dir whose target is outside must not carry the exemption to
+ * the file a write would create), and a genuinely missing tail keys as the
+ * canonicalized parent plus the basename (a not-yet-created target). */
+async function canonicalKey(absolute, depth = 0) {
+    if (depth > 32) {
+        // A symlink chain too deep to resolve (a loop, or just a legitimately
+        // deep chain): the key falls back to the raw path (treated as an
+        // ordinary unread target — fail-safe) and the trip reaches the trail
+        // with the depth, so a confusing refusal on such a path is diagnosable —
+        // same intent as the sibling catch trails. "depth" not "loop": the cap
+        // fires for deep non-looping chains too.
+        logEvent({
+            source: "fileGuards",
+            level: "info",
+            event: "canonical_key_depth_guard",
+            fields: { depth },
+        });
+        return absolute;
+    }
+    try {
+        return await fs.realpath(absolute);
+    }
+    catch {
+        const stat = await fs.lstat(absolute).catch(() => null);
+        if (stat?.isSymbolicLink()) {
+            const target = await fs.readlink(absolute);
+            return canonicalKey(path.resolve(path.dirname(absolute), target), depth + 1);
+        }
+        const parent = path.dirname(absolute);
+        if (parent === absolute)
+            return absolute; // filesystem root
+        return path.join(await canonicalKey(parent, depth), path.basename(absolute));
+    }
+}
+/** Default disk read, typed as string (fs.readFile's overload returns a
+ * buffer union the tracker's seam does not). */
+async function readTextFile(p) {
+    return (await fs.readFile(p)).toString("utf-8");
+}
+/**
+ * Session read state. One instance per registration (created by
+ * registerCondensedTools), so driver, `/go` stage children, and subagents
+ * each track their own session's reads — matching Claude Code's
+ * per-conversation readFileState.
+ */
+export class ReadStateTracker {
+    scratchpadDir;
+    io;
+    reads = new Map();
+    constructor(
+    /** Session scratchpad dir; paths under it are exempt from the guards. */
+    scratchpadDir, 
+    /** Stat/read seams for tests. */
+    io = {}) {
+        this.scratchpadDir = scratchpadDir;
+        this.io = io;
+    }
+    /** Record a successful read of `rawPath` (resolved against `cwd`). */
+    async recordRead(rawPath, cwd, text, partial) {
+        return this.capture(rawPath, cwd, { content: text, partial });
+    }
+    /** Record a successful write (the written content is the fresh truth). */
+    async recordWrite(rawPath, cwd, content) {
+        return this.capture(rawPath, cwd, { content, partial: false });
+    }
+    /** Refresh a record from disk after a successful edit (content unknown to us). */
+    async refreshFromDisk(rawPath, cwd) {
+        return this.capture(rawPath, cwd, {});
+    }
+    async capture(rawPath, cwd, known) {
+        const absolute = path.resolve(cwd, rawPath);
+        try {
+            const stat = await (this.io.stat ?? fs.stat)(absolute);
+            const content = known.content ?? await (this.io.readFile ?? readTextFile)(absolute);
+            // Floor at RECORD time as well as compare time (Claude Code's shape):
+            // a full-precision recorded mtime (ns fraction) would always exceed the
+            // floored current one and the staleness check would never fire.
+            const key = await canonicalKey(absolute);
+            this.reads.set(key, {
+                content,
+                mtimeMs: Math.floor(stat.mtimeMs),
+                partial: known.partial ?? false,
+            });
+        }
+        catch (error) {
+            // The file vanished between the tool result and the capture, or stat
+            // failed — the record stays absent and the NEXT write treats the file
+            // as unread. Fail-safe, never fail-loud — but never silent either:
+            // info (not debug — the durable trail filters debug out of a default
+            // session) so a later "unread" refusal after a successful read is
+            // diagnosable without a repro.
+            logEvent({
+                source: "fileGuards",
+                level: "info",
+                event: "record_capture_failed",
+                fields: { code: error?.code ?? "unknown" },
+            });
+        }
+    }
+    /**
+     * Throw one of the two refusals when the write/edit must not proceed.
+     * Resolves (returns) when the overwrite may continue; rethrows any fs
+     * error it did not classify, so the wrapper can fail open.
+     */
+    async assertFreshRead(rawPath, cwd) {
+        const absolute = path.resolve(cwd, rawPath);
+        const key = await canonicalKey(absolute);
+        if (this.scratchpadDir) {
+            const scratchKey = await canonicalKey(path.resolve(this.scratchpadDir));
+            if (this.isInside(key, scratchKey)) {
+                return; // permission-free scratchpad writes stay silent (never refuse)
+            }
+        }
+        let mtimeMs;
+        try {
+            mtimeMs = (await (this.io.stat ?? fs.stat)(key)).mtimeMs;
+        }
+        catch (error) {
+            const code = error?.code;
+            if (code === "ENOENT")
+                return; // a new-file create — no prior read needed
+            throw error; // unknown fs failure — the wrapper fails open
+        }
+        const record = this.reads.get(key);
+        if (!record || record.partial) {
+            throw new Error(READ_FIRST_ERROR);
+        }
+        if (Math.floor(mtimeMs) > record.mtimeMs) {
+            // Timestamp moved, but on some platforms (cloud sync, antivirus) it
+            // moves without content changes. For a full read, compare content
+            // before refusing — Claude Code's exact fallback. The record holds
+            // the read tool's exact output and pi returns file bytes verbatim,
+            // so identical content compares byte-equal.
+            let onDisk;
+            try {
+                onDisk = await (this.io.readFile ?? readTextFile)(key);
+            }
+            catch (error) {
+                // Unreadable now, but the read succeeded then — stale — but the real
+                // cause (EACCES/EIO on the re-read, not an edit) rides the trail so
+                // the refusal is not misdiagnosed as a content change.
+                logEvent({
+                    source: "fileGuards",
+                    level: "info",
+                    event: "staleness_reread_failed",
+                    fields: { code: error?.code ?? "unknown" },
+                });
+                throw new Error(STALE_ERROR);
+            }
+            if (onDisk !== record.content) {
+                throw new Error(STALE_ERROR);
+            }
+            // Content-identical: refresh the record so the next write's mtime
+            // comparison uses the bumped timestamp instead of refusing again.
+            this.reads.set(key, { ...record, mtimeMs: Math.floor(mtimeMs) });
+        }
+    }
+    isInside(absolute, base) {
+        const slashed = (p) => p.replace(/\\/g, "/");
+        const a = slashed(absolute);
+        const b = slashed(base).replace(/\/+$/, "");
+        return a === b || a.startsWith(`${b}/`);
+    }
+}
+//# sourceMappingURL=fileGuards.js.map

package/dist/extension/index.js

@@ -1248,8 +1248,18 @@ export async function registerYagni(pi, deps = {}) {
     // eval mode keeps pi's stock registration (measured behavior stays
     // byte-identical) and the desktop surface keeps the structured pipeline.
     // YAGNI_CLASSIC_TOOL_ROWS=1 is the debugging escape hatch back to pi's
-    // boxed renderers.
-    if (!evalMode && !isDesktopSurface() && env.YAGNI_CLASSIC_TOOL_ROWS !== "1") {
+    // boxed renderers. The file-tool guards and the guarded write/edit
+    // descriptions ride this SAME registration, so the steering prompt section
+    // (which promises those guards) is injected only when this is active —
+    // eval mode stays byte-identical and desktop never gets a promise the
+    // tools there don't keep.
+    const condensedToolsWanted = !evalMode && !isDesktopSurface() && env.YAGNI_CLASSIC_TOOL_ROWS !== "1";
+    // The steering flag tracks the registration OUTCOME, not the condition:
+    // the catch below keeps activation alive when registration throws, and a
+    // throw means the guards never went live — the prompt section that
+    // promises them must not ship either.
+    let condensedToolsRegistered = false;
+    if (condensedToolsWanted) {
         try {
             registerCondensedTools(pi, {
                 ...(scratchpadDirPath ? { scratchpadDir: scratchpadDirPath } : {}),
@@ -1258,6 +1268,7 @@ export async function registerYagni(pi, deps = {}) {
                 // the sandbox is off.
                 ...(sandboxHandle ? { wrapBash: sandboxHandle.composeBash } : {}),
             });
+            condensedToolsRegistered = true;
         }
         catch {
             // Rendering must never break activation; pi's built-ins remain.
@@ -1307,6 +1318,7 @@ export async function registerYagni(pi, deps = {}) {
                 rulesSection,
                 scratchpadSection: scratchpadSectionText,
                 attributionSection: attributionPromptSection(attribution()),
+                fileToolSteering: condensedToolsRegistered,
             }),
         });
     // Turn-lifecycle WAL: a `turn_start` with no matching `turn_end` is the

package/dist/extension/sandbox/bash.d.ts

@@ -127,13 +127,64 @@ export declare function shouldUseSandboxForUserCommand(command: string, manager:
  * advisory only, never a grant. Uninitialized manager ⇒ passthrough, no
  * hint (no annotation context, and the sink is not wired yet).
  */
-export declare function annotateCommandOutput(manager: YagniSandboxManager, command: string, output: string): {
+export declare function annotateCommandOutput(manager: YagniSandboxManager, command: string, output: string, fsScope?: {
+    cwd: string;
+    scope: FsDenialScope;
+}): {
     text: string;
     net: {
         cls: NetworkDenialClass;
         hint: string;
     } | null;
+    fs: {
+        cls: FsDenialClass;
+        hint: string;
+    } | null;
 };
+/** The filesystem denial classes this classifier knows (closed set — rides
+ * the sink line as a low-cardinality field, the same contract as
+ * NetworkDenialClass). write-scope-protected is a distinct class (not a
+ * sub-case) because its REMEDY differs: protected paths can never be
+ * admitted with an allow rule, so the hint must not point at the knob. */
+export type FsDenialClass = "write-scope" | "write-scope-protected" | "heredoc-cwd";
+/** The writable/denied root lists the fs classifier needs, passed in by the
+ * caller so the classifier stays pure (the established pattern — see
+ * networkDenialHint). allowWrite: the sandbox's writable roots (session cwd,
+ * the temp dirs, config allowWrite). denyWrite: the protected paths that are
+ * denied even when a wider allow would cover them (config files, state dirs). */
+export interface FsDenialScope {
+    allowWrite: readonly string[];
+    denyWrite: readonly string[];
+}
+/**
+ * Classify a sandbox filesystem denial from command + output. Pure;
+ * advisory-only (the fs twin of networkDenialHint — never widens anything,
+ * the remedy is model-side or a user config edit, never a grant). Matches
+ * the signatures observed live and in the session review:
+ *   - heredoc-cwd:        `cannot create temp file for here document` /
+ *                         `/dev/fd/NN: Operation not permitted` — bash 3.2
+ *                         writes heredoc temp files relative to the CURRENT
+ *                         directory, so a cd outside the writable roots makes
+ *                         every heredoc fail even when the target is writable
+ *                         (reproduced live; the e2b /dev/fd/62 case is the
+ *                         process-substitution sibling of the same mechanism)
+ *   - write-scope:         an EPERM whose line names a write TARGET path
+ *                         outside the writable roots — the literal `/tmp`
+ *                         writes observed in the sessions (`cat > /tmp/x`,
+ *                         `> /tmp/after.txt`, python PermissionError on a
+ *                         non-root path)
+ *   - write-scope-protected: same shape but the target is a PROTECTED path
+ *                         (denyWrite) — the config.json / state-dir denies.
+ *                         Protected paths can never be admitted with allow
+ *                         rules, so the hint copy differs.
+ * Returns null when the output carries no fs-denial signature — a network
+ * denial must NOT get an fs hint (the pinned negative in networkDenialHint
+ * is symmetric here).
+ */
+export declare function fsDenialHint(command: string, output: string, cwd: string, scope: FsDenialScope): {
+    cls: FsDenialClass;
+    hint: string;
+} | null;
 /** cwd must exist before spawn (guard borrowed from pi's local ops). */
 export declare function assertSpawnableCwd(cwd: string): void;
 /**

package/dist/extension/sandbox/bash.js

@@ -21,6 +21,7 @@
  * lessons (process-group kill, stdio release).
  */
 import { existsSync } from "node:fs";
+import { join } from "node:path";
 import { logEvent } from "../errorSink.js";
 import { scrubSecrets } from "../pipeline/scrubSecrets.js";
 function stripLeadingSafeEnvVars(command) {
@@ -347,18 +348,128 @@ export function shouldUseSandboxForUserCommand(command, manager, settings) {
  * advisory only, never a grant. Uninitialized manager ⇒ passthrough, no
  * hint (no annotation context, and the sink is not wired yet).
  */
-export function annotateCommandOutput(manager, command, output) {
+export function annotateCommandOutput(manager, command, output, fsScope) {
     if (!manager.initialized)
-        return { text: output, net: null };
+        return { text: output, net: null, fs: null };
     const net = networkDenialHint(output);
     if (!output.includes("Operation not permitted") && !net)
-        return { text: output, net: null };
+        return { text: output, net: null, fs: null };
     const annotated = output.includes("Operation not permitted")
         ? manager.annotateStderrWithSandboxFailures(command, output)
         : output;
-    if (!net)
-        return { text: annotated, net: null };
-    return { text: `${annotated}\n\n[sandbox] ${net.hint}`, net };
+    // The fs classification: same regex surface, same composition position,
+    // but the NETWORK hint wins when both classify (network denials have a
+    // user-flippable knob; fs remedies are model-side). When net wins, fs
+    // returns null — the callers log BOTH returns unconditionally, so a
+    // non-null loser would emit a second census line for one denial.
+    const fs = net
+        ? null
+        : fsScope
+            ? fsDenialHint(command, output, fsScope.cwd, fsScope.scope)
+            : null;
+    const hint = net ?? fs;
+    if (!hint)
+        return { text: annotated, net: null, fs: null };
+    return { text: `${annotated}\n\n[sandbox] ${hint.hint}`, net, fs };
+}
+/** Is `p` at or under one of the roots? Prefix match on path-segment
+ * boundaries (`/var/folders/T` must not admit `/var/folders/T-evil`). */
+function underRoot(p, roots) {
+    return roots.some((r) => {
+        if (p === r)
+            return true;
+        return p.startsWith(r.endsWith("/") ? r : r + "/");
+    });
+}
+/** Does the command carry a heredoc marker or a process substitution, plus a
+ * cd to a directory outside the writable roots? The discriminator for the
+ * heredoc-cwd drift shape: the temp-file write follows the shell's CURRENT
+ * directory, so a heredoc from inside the roots never has this failure —
+ * only the cd-drifted form does. */
+function hasHeredocCwdDrift(command, cwd, scope) {
+    if (!/<<|<\(/.test(command))
+        return false;
+    // find every cd target and require at least one OUTSIDE the writable roots
+    const cdRe = /(^|[\n;&|(\s])cd\s+([^\n;&|)\s]+)/g;
+    let m;
+    while ((m = cdRe.exec(command)) !== null) {
+        const target = m[2].replace(/^("|')+|("|')+$/g, "");
+        // Resolve the same way a shell would for the classification question:
+        // absolute as-is, ~ against HOME (the common drift target), relative
+        // against the session cwd (a relative cd stays inside the roots only if
+        // the resolved path is under them).
+        let resolved = null;
+        if (target.startsWith("/"))
+            resolved = target;
+        else if (target.startsWith("~"))
+            resolved = target.replace(/^~/, process.env.HOME ?? "~");
+        else if (target !== "-" && !target.startsWith("$"))
+            resolved = join(cwd, target);
+        if (resolved && !underRoot(resolved, scope.allowWrite))
+            return true;
+    }
+    return false;
+}
+/**
+ * Classify a sandbox filesystem denial from command + output. Pure;
+ * advisory-only (the fs twin of networkDenialHint — never widens anything,
+ * the remedy is model-side or a user config edit, never a grant). Matches
+ * the signatures observed live and in the session review:
+ *   - heredoc-cwd:        `cannot create temp file for here document` /
+ *                         `/dev/fd/NN: Operation not permitted` — bash 3.2
+ *                         writes heredoc temp files relative to the CURRENT
+ *                         directory, so a cd outside the writable roots makes
+ *                         every heredoc fail even when the target is writable
+ *                         (reproduced live; the e2b /dev/fd/62 case is the
+ *                         process-substitution sibling of the same mechanism)
+ *   - write-scope:         an EPERM whose line names a write TARGET path
+ *                         outside the writable roots — the literal `/tmp`
+ *                         writes observed in the sessions (`cat > /tmp/x`,
+ *                         `> /tmp/after.txt`, python PermissionError on a
+ *                         non-root path)
+ *   - write-scope-protected: same shape but the target is a PROTECTED path
+ *                         (denyWrite) — the config.json / state-dir denies.
+ *                         Protected paths can never be admitted with allow
+ *                         rules, so the hint copy differs.
+ * Returns null when the output carries no fs-denial signature — a network
+ * denial must NOT get an fs hint (the pinned negative in networkDenialHint
+ * is symmetric here).
+ */
+export function fsDenialHint(command, output, cwd, scope) {
+    // heredoc-cwd first (most specific): the temp-file EPERM signatures, gated
+    // on the command actually carrying the drift shape.
+    if (/(cannot create temp file for here document|\/dev\/fd\/\d+: Operation not permitted)/.test(output) &&
+        hasHeredocCwdDrift(command, cwd, scope)) {
+        return {
+            cls: "heredoc-cwd",
+            hint: "This looks like a heredoc temp-file denial — bash writes heredoc temp files relative to the current directory, and a cd outside the writable roots makes every heredoc fail even when the heredoc target is writable. " +
+                "Run the heredoc from the working directory (no cd first), or use printf or a file in the working directory instead. Retrying with dangerouslyDisableSandbox is NOT needed.",
+        };
+    }
+    // write-target EPERM: the bash line shape (reusing extractBlockedWritePath's
+    // regex family) plus the python PermissionError shape.
+    const blocked = extractBlockedWritePath(output) ??
+        (output.match(/PermissionError: \[Errno \d+\] Operation not permitted: '([^']+)'/)?.[1] ?? null);
+    if (!blocked)
+        return null;
+    // A target inside the writable roots is NOT a write-scope denial — the
+    // scratchpad lives under the temp dir and its writes never hit the fence
+    // (the observed non-bug; pinned by test).
+    if (underRoot(blocked, scope.allowWrite))
+        return null;
+    if (underRoot(blocked, scope.denyWrite)) {
+        return {
+            cls: "write-scope-protected",
+            hint: "This looks like a sandbox write to a protected path — this path is denied even with allow rules (it holds the agent's own configuration). " +
+                "Do not write here; ask the user or use a different location. Retrying with dangerouslyDisableSandbox will still ask for permission and is the wrong tool for this — the protection is deliberate.",
+        };
+    }
+    return {
+        cls: "write-scope",
+        hint: "This looks like a sandbox write-scope denial — the target is outside the writable roots (the working directory and $TMPDIR). " +
+            "Use $TMPDIR or the project directory for temporary files. To write here anyway, add the path to sandbox.filesystem.allowWrite in your settings (the /sandbox panel's Config tab shows the current scope). " +
+            "Retrying with dangerouslyDisableSandbox is usually NOT needed — move the target inside the scope instead.",
+    };
 }
 /** cwd must exist before spawn (guard borrowed from pi's local ops). */
 export function assertSpawnableCwd(cwd) {

package/dist/extension/sandbox/session.d.ts

@@ -28,7 +28,10 @@ import type { PermissionRule } from "../permissionRules/loadConfig.js";
  * here would be overwritten and the sandbox would silently never reach
  * model-driven tool calls.
  */
-export declare function makeBashComposition(manager: YagniSandboxManager, settings: () => SandboxSettings, cwd: string, onShellResolutionRetry?: (outcome: "recovered" | "exhausted") => void): (def: ToolDefinition) => ToolDefinition;
+export declare function makeBashComposition(manager: YagniSandboxManager, settings: () => SandboxSettings, cwd: string, onShellResolutionRetry?: (outcome: "recovered" | "exhausted") => void, fsScope?: () => {
+    allowWrite: readonly string[];
+    denyWrite: readonly string[];
+} | null): (def: ToolDefinition) => ToolDefinition;
 export interface SandboxSessionHandle {
     manager: YagniSandboxManager;
     settings: () => SandboxSettings;

package/dist/extension/sandbox/session.js

@@ -23,7 +23,7 @@ import { isDebug } from "../diagnostics.js";
 import { mutateConfigJson, mutateLocalConfig } from "../settingsFiles.js";
 import { loadSandboxSettings } from "./config.js";
 import { resolveWorktreeGitAccess } from "./worktreeGit.js";
-import { annotateCommandOutput, makeSandboxSpawnHook, networkDenialHint, preWrappedCommand, shouldUseSandbox, shouldUseSandboxForUserCommand, } from "./bash.js";
+import { annotateCommandOutput, fsDenialHint, makeSandboxSpawnHook, networkDenialHint, preWrappedCommand, shouldUseSandbox, shouldUseSandboxForUserCommand, } from "./bash.js";
 import { YagniSandboxManager } from "./manager.js";
 import { SandboxPanel, buildPanelState, engineeringPresetBlock } from "./panel.js";
 import { effectiveRules } from "../permissionRules/loadConfig.js";
@@ -39,7 +39,7 @@ import { effectiveRules } from "../permissionRules/loadConfig.js";
  * here would be overwritten and the sandbox would silently never reach
  * model-driven tool calls.
  */
-export function makeBashComposition(manager, settings, cwd, onShellResolutionRetry) {
+export function makeBashComposition(manager, settings, cwd, onShellResolutionRetry, fsScope) {
     return (def) => {
         if (!settings().enabled)
             return def;
@@ -50,6 +50,12 @@ export function makeBashComposition(manager, settings, cwd, onShellResolutionRet
             shellPath: userShellPath,
             spawnHook,
         });
+        // The fs-denial classification scope (advisory hint only): resolved
+        // lazily per annotation — a denial is rare, the merge is not free.
+        const fsScopeForAnnotate = () => {
+            const scope = fsScope?.();
+            return scope ? { cwd, scope } : undefined;
+        };
         const schema = Type.Object({
             command: Type.String({ description: "The bash command to execute" }),
             timeout: Type.Optional(Type.Number({ description: "Optional timeout in seconds" })),
@@ -138,9 +144,11 @@ export function makeBashComposition(manager, settings, cwd, onShellResolutionRet
                         // The thrown-message gate matches the result-text gate: a
                         // network-signature denial in EITHER surface gets the
                         // annotation + hint (node throws lowercase "operation not
-                        // permitted", which the bare substring misses).
-                        const annotated = annotateCommandOutput(manager, input.command, err.message);
+                        // permitted", which the bare substring misses). The fs hint
+                        // composes under the same gate (one diagnosis, network wins).
+                        const annotated = annotateCommandOutput(manager, input.command, err.message, fsScopeForAnnotate());
                         logNetworkDenialHint(annotated.net);
+                        logFsDenialHint(annotated.fs, "thrown");
                         throw new Error(annotated.text);
                     }
                     throw err;
@@ -151,8 +159,9 @@ export function makeBashComposition(manager, settings, cwd, onShellResolutionRet
                 if (result?.content) {
                     const text = result.content.map((c) => (c.type === "text" ? c.text : "")).join("\n");
                     if (text.includes("Operation not permitted") || networkDenialHint(text)) {
-                        const annotated = annotateCommandOutput(manager, input.command, text);
+                        const annotated = annotateCommandOutput(manager, input.command, text, fsScopeForAnnotate());
                         logNetworkDenialHint(annotated.net);
+                        logFsDenialHint(annotated.fs, "result");
                         result = { ...result, content: [{ type: "text", text: annotated.text }] };
                     }
                 }
@@ -179,6 +188,33 @@ export function registerSandbox(pi, opts) {
     }).settings;
     let currentSettings = load();
     let rules = [];
+    // The fs-denial classification scope for the advisory hint (the roots
+    // the runtime merge resolves: cwd + tmpdir + config allowWrite, denied:
+    // the protected paths). Lazy + memo-invalidated per call — a denial is
+    // rare and buildRuntimeMerge is not free; re-reading per annotation also
+    // picks up rules/settings changes without a cache to invalidate.
+    const fsScope = () => {
+        if (!manager.initialized)
+            return null;
+        try {
+            const merge = manager.buildRuntimeMerge(rules);
+            return { allowWrite: merge.filesystem.allowWrite, denyWrite: merge.filesystem.denyWrite };
+        }
+        catch (err) {
+            // Never the thrown message (it can carry command content) — error
+            // class only, same posture as the gate's classify-error line. Without
+            // this trace a persistently-throwing merge would silently strip fs
+            // hints from all three surfaces and the only symptom would be "hints
+            // disappeared" from the census the measurement depends on.
+            logEvent({
+                source: "sandbox",
+                level: "warn",
+                event: "fs_scope_error",
+                fields: { error: err instanceof Error ? err.constructor.name : typeof err },
+            });
+            return null; // fail-soft: no scope, no hint (the network hint still rides)
+        }
+    };
     // Optional-chained: some harnesses/mocks don't implement flag APIs; the
     // flag simply reads as unset there. Real pi registers it normally.
     pi.registerFlag?.("no-sandbox", {
@@ -326,7 +362,7 @@ export function registerSandbox(pi, opts) {
         logShellResolutionRetry(outcome);
         opts.onShellResolutionRetry?.(outcome);
     };
-    const composeBash = makeBashComposition(manager, () => currentSettings, opts.cwd, onShellResolutionRetry);
+    const composeBash = makeBashComposition(manager, () => currentSettings, opts.cwd, onShellResolutionRetry, fsScope);
     const registerOwnBash = () => {
         if (!currentSettings.enabled)
             return;
@@ -409,11 +445,22 @@ export function registerSandbox(pi, opts) {
                         throw new Error(`timeout:${timeout}`);
                     // Post-run hint: same advisory as the tool path, appended after
                     // the child's own output so the user sees the fix pointer inline.
+                    // One diagnosis per denial: the network hint wins when both
+                    // classify (network has a user knob; fs remedies are model-side).
+                    // A null fsScope() (uninitialized manager, merge error) skips the
+                    // fs classification entirely — an empty-roots fallback would
+                    // misclassify in-roots and protected targets as write-scope.
                     const net = networkDenialHint(tail);
+                    const scope = net ? null : fsScope();
+                    const fs = scope ? fsDenialHint(event.command, tail, opts.cwd, scope) : null;
                     if (net) {
                         logEvent({ source: "sandbox", level: "info", event: "network_denial_hint", fields: { class: net.cls } });
                         onData(Buffer.from(`\n[sandbox] ${net.hint}`));
                     }
+                    else if (fs) {
+                        logEvent({ source: "sandbox", level: "info", event: "fs_denial_hint", fields: { class: fs.cls, surface: "user-bash" } });
+                        onData(Buffer.from(`\n[sandbox] ${fs.hint}`));
+                    }
                     return { exitCode };
                 }
                 finally {
@@ -825,6 +872,15 @@ function logNetworkDenialHint(net) {
         return;
     logEvent({ source: "sandbox", level: "info", event: "network_denial_hint", fields: { class: net.cls } });
 }
+/** Sink line for the fs-denial hint (same low-cardinality contract as the
+ * network one — the before/after escape census reads these lines). The
+ * surface field distinguishes the tool-call thrown-error / result-text /
+ * !-command call sites in the log stream. */
+function logFsDenialHint(fs, surface) {
+    if (!fs)
+        return;
+    logEvent({ source: "sandbox", level: "info", event: "fs_denial_hint", fields: { class: fs.cls, surface } });
+}
 /** Sink line for a failed domain-grant persist — the thrown message is
  * mutateConfigJson's own path/reason text (diagnosable, no file content),
  * same posture as sandbox_persist_failed / rule_save_failed. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yagni-app/code-staging",
-  "version": "1.1.2-staging.1368.1",
+  "version": "1.1.2-staging.1370.1",
   "description": "YAGNI Code: a terminal coding agent that already knows your company. One YAGNI login routes the model and grounds the agent in your team's context.",
   "license": "SEE LICENSE IN LICENSE.md",
   "author": "YAGNI, Inc. <jack@yagni.app> (https://yagni.app)",
@@ -58,5 +58,5 @@
     "turndown": "^7.2.4",
     "typebox": "^1.3.15"
   },
-  "yagniSourceSha": "a5f338426410c8549a0b85f6e0ac39fd3fdd3e78"
+  "yagniSourceSha": "2f7255058068c24ee9b070aec43e23b4fc32fb39"
 }