@yagni-app/code-staging 1.1.2-staging.1369.1 → 1.1.2-staging.1372.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

@@ -36,8 +36,10 @@ import { registerGoCommand } from "./pipeline/goCommand.js";
 import { registerGoCompareCommand } from "./pipeline/goCompareCommand.js";
 import { DEFAULT_PERMISSION_POLICY, createModeHolder, registerPermissionGate } from "./permission/gate.js";
 import { registerSandbox } from "./sandbox/session.js";
-import { sandboxAutoAllowDecision } from "./sandbox/bash.js";
+import { isSandboxDenialOutput, sandboxAutoAllowDecision, sandboxDenialSignature, shouldUseSandbox } from "./sandbox/bash.js";
+import { sandboxFailureKey } from "./permission/approvedPrefixes.js";
 import { createEscapeTally } from "./sandbox/escapeTally.js";
+import { createGrantCensus } from "./permission/grantCensus.js";
 import { registerTelemetry as defaultRegisterTelemetry } from "./telemetry/register.js";
 import { loadHooksConfig, makeHookRunner, registerHooks } from "./hooks.js";
 import { loadPermissionRules } from "./permissionRules/loadConfig.js";
@@ -723,6 +725,37 @@ export async function registerYagni(pi, deps = {}) {
     // the startup load is the trust boundary; live reload was reviewed and
     // rejected as a same-session self-authorization path, PR #1698).
     const sessionGrants = evalMode ? [] : loadGrants();
+    // Prior sandboxed failures (the auto-sandbox rung's session state): a
+    // bash tool_result whose output carries a sandbox-denial signature marks
+    // the command — its later escape attempts go to the consent dialog (the
+    // sandbox genuinely cannot run it). Content stays local: only the trimmed
+    // command string is held in memory, never logged.
+    const sandboxedFailures = new Map();
+    const SANDBOXED_FAILURES_MAX = 50;
+    const recordSandboxedFailure = (command) => {
+        // The CANONICAL key (sandboxFailureKey): a retry differing by quote
+        // rendering or safe decoration must hit the same entry — raw-string
+        // keys would miss exactly the variable shapes the grants layer
+        // canonicalizes for.
+        const key = sandboxFailureKey(command);
+        if (!key)
+            return;
+        sandboxedFailures.delete(key);
+        sandboxedFailures.set(key, true);
+        if (sandboxedFailures.size > SANDBOXED_FAILURES_MAX) {
+            const oldest = sandboxedFailures.keys().next().value;
+            if (oldest !== undefined)
+                sandboxedFailures.delete(oldest);
+        }
+    };
+    const hasSandboxedFailure = (command) => sandboxedFailures.has(sandboxFailureKey(command));
+    // A mode transition is a trust-posture change — the auto-sandbox rung's
+    // prior-failure evidence clears with the gate's other session caches
+    // (the gate's own fallback map clears via modeHolder.onSet; this map is
+    // the production one, so it must clear here too).
+    modeHolder.onSet(() => {
+        sandboxedFailures.clear();
+    });
     // settings-based permission rules, loaded once at startup (same
     // trust-boundary posture as grants: no mid-session reload). User config
     // (~/.yagni-code/config.json) + project config (.yagni-code/config.json);
@@ -758,6 +791,11 @@ export async function registerYagni(pi, deps = {}) {
     // shared by the gate (record), the /sandbox panel (breakdown), and the
     // session-end summary line.
     const escapeTally = createEscapeTally();
+    // The session grant census (telemetry-only): every grant the session
+    // loaded plus every match, for the /sandbox panel's never-matched
+    // surfacing. Nothing is pruned, nothing is written back to rules.json.
+    const grantCensus = createGrantCensus();
+    grantCensus.seed(sessionGrants);
     const sandboxHandle = evalMode
         ? null
         : registerSandbox(pi, {
@@ -766,6 +804,9 @@ export async function registerYagni(pi, deps = {}) {
             hasUI: (ctx) => ctx.hasUI,
             onShellResolutionRetry: (outcome) => telemetry.sandboxShellResolutionRetry(outcome),
             escapeBreakdown: () => escapeTally.breakdown(),
+            // The grant census snapshot for the /sandbox panel's grants
+            // section (session-scoped match counts + never-matched labels).
+            grantCensus: () => grantCensus.entries(),
             // Anchors project-protected paths (.yagni-code + its config.json in
             // denyWrite) and project-sourced permission rules to the repo the
             // session runs in — same root the gate uses for its rule anchoring.
@@ -785,6 +826,18 @@ export async function registerYagni(pi, deps = {}) {
                     sandboxHandle.manager.initialized &&
                     params.dangerouslyDisableSandbox === true &&
                     sandboxHandle.settings().allowUnsandboxedCommands !== false,
+                // The auto-sandbox rung's would-run-wrapped proof: after the gate
+                // strips the flag, this command must actually be wrapped by
+                // shouldUseSandbox — an excludedCommands entry (or a manager reset)
+                // would otherwise run it UNSANDBOXED with zero consent. The gate
+                // additionally requires its own allow classification before it
+                // consults this predicate.
+                sandboxEscapeAutoSandbox: (command) => shouldUseSandbox({ command, dangerouslyDisableSandbox: false }, sandboxHandle.manager, sandboxHandle.settings()),
+                recordSandboxedFailure,
+                hasSandboxedFailure,
+                // Grant census feed: every grant match (prompt band + escape flow)
+                // counts toward the never-matched surfacing in /sandbox.
+                onGrantMatch: (grant) => grantCensus.record(grant),
                 // Escape tally: interception-time, content-free on the always-on
                 // info tier (the command prefix is command content — it rides the
                 // debug tier only, same contract as logGateOutcomeTrail; the OTel
@@ -1248,8 +1301,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 +1321,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 +1371,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
@@ -1658,12 +1723,39 @@ export async function registerYagni(pi, deps = {}) {
     pi.on("tool_result", (event) => {
         if (event.toolName !== "bash")
             return;
-        const command = typeof event.input?.command === "string"
-            ? event.input.command
-            : "";
+        const input = (event.input ?? {});
+        const command = typeof input.command === "string" ? input.command : "";
         if (GIT_MUTATING_PATTERN.test(command)) {
             footerInvalidateHandle.invalidateGit();
         }
+        // The auto-sandbox rung's prior-failure evidence: a SANDBOXED bash
+        // result carrying a sandbox-denial signature marks this command — its
+        // later escape attempts re-arm the consent dialog instead of
+        // auto-sandboxing into the same denial forever. Only sandboxed runs
+        // count (an escaped run's failure text proves nothing about the
+        // sandbox); only the trimmed command is kept, never logged.
+        if (sandboxHandle &&
+            !input.dangerouslyDisableSandbox &&
+            event.isError &&
+            command) {
+            const text = (event.content ?? [])
+                .map((c) => (c && typeof c === "object" && "text" in c ? String(c.text) : ""))
+                .join("\n");
+            if (isSandboxDenialOutput(text)) {
+                recordSandboxedFailure(command);
+                // The seed must be observable (debug tier only — no command content,
+                // the closed signature class rides the field): a false-positive seed
+                // session-long disables auto-sandbox for a command, and without this
+                // line the only symptom would be unexplained dialogs.
+                const signature = sandboxDenialSignature(text);
+                logEvent({
+                    source: "sandbox",
+                    level: "debug",
+                    event: "sandbox_failure_seeded",
+                    fields: { signature },
+                });
+            }
+        }
     });
     // Seed the unified error trail from tool-exec failures. A tool's SUCCESS
     // is content (it lives in the transcript); its FAILURE is an error and belongs