one-code-extension 0.1.3 → 0.3.0

package/extensions/doctor/viewer.ts

@@ -0,0 +1,124 @@
+/**
+ * The `/doctor` panel (pure): a read-only, scrollable view of the rendered
+ * report inside `ctx.ui.custom`, with the key hints on screen (a hidden key is
+ * an undiscoverable key). The wiring owns repaint and the fix/close effects.
+ */
+
+import { panelTopRule } from "../lib/tui-render.ts";
+
+export interface DoctorViewerState {
+	offset: number;
+}
+
+export type DoctorViewerKey =
+	| { kind: "up" }
+	| { kind: "down" }
+	| { kind: "pageUp" }
+	| { kind: "pageDown" }
+	| { kind: "home" }
+	| { kind: "end" }
+	| { kind: "fix" }
+	| { kind: "close" };
+
+export function decodeDoctorKey(data: string): DoctorViewerKey | undefined {
+	switch (data) {
+		case "\x1b[A":
+		case "\x1bOA":
+		case "k":
+			return { kind: "up" };
+		case "\x1b[B":
+		case "\x1bOB":
+		case "j":
+			return { kind: "down" };
+		case "\x1b[5~":
+		case "\x02": // ctrl+b
+		case "b":
+			return { kind: "pageUp" };
+		case "\x1b[6~":
+		case "\x06": // ctrl+f
+		case " ":
+			return { kind: "pageDown" };
+		case "\x1b[H":
+		case "\x1b[1~":
+		case "g":
+			return { kind: "home" };
+		case "\x1b[F":
+		case "\x1b[4~":
+		case "G":
+			return { kind: "end" };
+		case "f":
+			return { kind: "fix" };
+		case "\x1b":
+		case "\x03": // ctrl+c
+		case "q":
+		case "\r":
+		case "\n":
+			return { kind: "close" };
+		default:
+			return undefined;
+	}
+}
+
+export type DoctorViewerEffect = { kind: "fix" } | { kind: "close" };
+
+/** Move the window; returns an effect for keys the wiring must act on. */
+export function applyDoctorKey(state: DoctorViewerState, key: DoctorViewerKey, total: number, visible: number): DoctorViewerEffect | undefined {
+	const max = Math.max(0, total - visible);
+	const page = Math.max(1, visible - 1);
+	switch (key.kind) {
+		case "up":
+			state.offset = Math.max(0, state.offset - 1);
+			return undefined;
+		case "down":
+			state.offset = Math.min(max, state.offset + 1);
+			return undefined;
+		case "pageUp":
+			state.offset = Math.max(0, state.offset - page);
+			return undefined;
+		case "pageDown":
+			state.offset = Math.min(max, state.offset + page);
+			return undefined;
+		case "home":
+			state.offset = 0;
+			return undefined;
+		case "end":
+			state.offset = max;
+			return undefined;
+		case "fix":
+			return { kind: "fix" };
+		case "close":
+			return { kind: "close" };
+	}
+}
+
+export interface DoctorViewerInput {
+	/** Already rendered (painted, width-cut) report lines. */
+	lines: string[];
+	state: DoctorViewerState;
+	width: number;
+	/** Total rows the panel may occupy, chrome included. */
+	height: number;
+	/** Whether a model is available, so the `f` hint is shown. */
+	canFix: boolean;
+}
+
+/** Rows taken by the top rule and the footer hint. */
+export const VIEWER_CHROME_ROWS = 3;
+
+export function visibleBodyRows(height: number): number {
+	return Math.max(1, height - VIEWER_CHROME_ROWS);
+}
+
+export function renderDoctorViewer(input: DoctorViewerInput, paint: (color: string, text: string) => string): string[] {
+	const { lines, state, width, height } = input;
+	const visible = visibleBodyRows(height);
+	const max = Math.max(0, lines.length - visible);
+	if (state.offset > max) state.offset = max;
+	const window = lines.slice(state.offset, state.offset + visible);
+	while (window.length < visible) window.push("");
+	const position = lines.length > visible ? ` · ${state.offset + 1}-${Math.min(lines.length, state.offset + visible)} of ${lines.length}` : "";
+	// PageUp/PageDown are pi-tui's own scrollback keys in fullscreen mode and never
+	// reach a component, so the hint names keys that do.
+	const hints = [`↑/↓ scroll · space/b page · g/G top/end${position}`, ...(input.canFix ? ["f run the checkup (the model fixes the findings)"] : []), "esc close"].join(" · ");
+	return [panelTopRule(paint, width), ...window, "", paint("dim", ` ${hints}`)];
+}

package/extensions/effort/index.ts

@@ -21,13 +21,14 @@ import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import { getSupportedThinkingLevels } from "@earendil-works/pi-ai/compat";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { REMINDER_CHANNEL } from "../lib/reminders.ts";
-import { safeThemePaint } from "../lib/tui-render.ts";
+import { dimRightAlignedWidget, safeThemePaint, truncateLine } from "../lib/tui-render.ts";
 import {
 	acceptedEffortArgs,
 	choiceForState,
 	decodeKey,
 	type EffortChoice,
 	EFFORT_CHOICES,
+	effortNoteText,
 	enabledStops,
 	levelRank,
 	moveIndex,
@@ -38,6 +39,8 @@ import {
 	thinkingLevelFor,
 	ULTRACODE,
 	ULTRACODE_LEVEL,
+	ULTRACODE_MODE_CHANNEL,
+	ULTRACODE_STATUS_KEY,
 } from "./slider.ts";
 
 /** The levels pi says the active model can reach; the full ladder when unknown. */
@@ -51,7 +54,8 @@ function modelLabel(ctx: ExtensionContext): string {
 }
 
 const REMINDER_KEY = "ultracode-mode";
-const STATUS_KEY = "ultracode";
+const NOTE_KEY = "effort-note";
+const NOTE_MS = 5000;
 
 /**
  * The standing instruction for ultracode mode. Deliberately stronger than the
@@ -77,17 +81,44 @@ export default function effortExtension(pi: ExtensionAPI) {
 
 	const applyStatus = (ctx: ExtensionContext) => {
 		// No-op outside the TUI, so this is safe to call unconditionally.
-		ctx.ui.setStatus(STATUS_KEY, ultracodeActive ? "✦ ultracode" : undefined);
+		ctx.ui.setStatus(ULTRACODE_STATUS_KEY, ultracodeActive ? "✦ ultracode" : undefined);
 	};
 
+	/**
+	 * Claude Code's effort-changed note: "● high · /effort", right-aligned above
+	 * the input for a few seconds after the level changes.
+	 */
+	let noteTimer: ReturnType<typeof setTimeout> | undefined;
+	const showEffortNote = (ctx: ExtensionContext, level: ThinkingLevel) => {
+		if (!ctx.hasUI) return;
+		ctx.ui.setWidget(NOTE_KEY, dimRightAlignedWidget(effortNoteText(level, ultracodeActive)), {
+			placement: "aboveEditor",
+		});
+		if (noteTimer) clearTimeout(noteTimer);
+		noteTimer = setTimeout(() => ctx.ui.setWidget(NOTE_KEY, undefined), NOTE_MS);
+		noteTimer.unref?.();
+	};
+	// The timer captured the ctx of the turn that changed the level; a /clear or
+	// shutdown inside the note's few seconds invalidates that ctx, and pi throws
+	// on a stale ctx use. Drop the timer with the session instead.
+	const cancelEffortNote = () => {
+		if (noteTimer) clearTimeout(noteTimer);
+		noteTimer = undefined;
+	};
+	pi.on("session_start", cancelEffortNote);
+	pi.on("session_shutdown", cancelEffortNote);
+
 	const setUltracode = (on: boolean, level?: ThinkingLevel) => {
+		const changed = ultracodeActive !== on;
 		ultracodeActive = on;
 		ultracodeLevel = on ? level : undefined;
+		if (changed) pi.events.emit(ULTRACODE_MODE_CHANNEL, { active: on });
 		if (on) {
 			pi.events.emit(REMINDER_CHANNEL, {
 				text: ULTRACODE_STANDING_REMINDER,
 				scope: "every-turn",
 				key: REMINDER_KEY,
+				placement: "sticky-append",
 			});
 		} else {
 			pi.events.emit(REMINDER_CHANNEL, { remove: true, key: REMINDER_KEY });
@@ -102,6 +133,7 @@ export default function effortExtension(pi: ExtensionAPI) {
 
 		setUltracode(choice === ULTRACODE, actual);
 		applyStatus(ctx);
+		showEffortNote(ctx, actual);
 
 		// setThinkingLevel clamps to model capability silently. Only flag a genuine
 		// downward clamp (the model can't reach the requested level); an upward clamp
@@ -135,7 +167,11 @@ export default function effortExtension(pi: ExtensionAPI) {
 		const chosen = await ctx.ui.custom<EffortChoice | null>((tui, theme, _keybindings, done) => {
 			const paint = safeThemePaint(theme);
 			return {
-				render: (width: number) => ["", ...renderEffortSlider({ index, enabled, width, modelLabel: label }, paint), ""],
+				// The slider's own layout is column-safe for its ASCII labels, but this
+				// dialog has no linesComponent wrap, so a final truncate is the safety
+				// net that guarantees no overwide line reaches pi-tui (TUI-REVIEW H1/H2).
+				render: (width: number) =>
+					["", ...renderEffortSlider({ index, enabled, width, modelLabel: label }, paint), ""].map((line) => truncateLine(line, width)),
 				handleInput: (data: string) => {
 					const key = decodeKey(data);
 					if (!key) return;
@@ -208,6 +244,7 @@ export default function effortExtension(pi: ExtensionAPI) {
 			applyStatus(ctx);
 			ctx.ui.notify(`Ultracode off — reasoning is now ${event.level}`, "info");
 		}
+		showEffortNote(ctx, event.level);
 	});
 
 	pi.on("session_start", (_event, ctx) => {

package/extensions/effort/slider.ts

@@ -22,6 +22,21 @@ import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 /** The final stop on the track: top reasoning + workflows armed every turn. */
 export const ULTRACODE = "ultracode";
 
+/** UI status key the effort extension sets while ultracode is armed; the footer
+ * reads it to show "✦ ultracode" in place of the effort level. Shared via this
+ * pure module so both extensions reference one constant, not a bare string. */
+export const ULTRACODE_STATUS_KEY = "ultracode";
+
+/**
+ * Event-bus channel the effort extension emits `{ active: boolean }` on when
+ * ultracode mode switches. The workflow extension listens so the keyword
+ * one-shot ("the user included ultracode") is skipped while the standing block
+ * already says so — two instructions for one fact, the weaker one on top,
+ * steered worse than one. Emitted on change only (the bus does not replay);
+ * the mode starts off, so a listener registered at load is never behind.
+ */
+export const ULTRACODE_MODE_CHANNEL = "one-code:ultracode-mode";
+
 /** The reasoning level ultracode pins, when the model can reach it. */
 export const ULTRACODE_LEVEL: ThinkingLevel = "xhigh";
 
@@ -163,8 +178,10 @@ export interface SliderView {
 }
 
 const TITLE = "Effort";
-const HINTS = "←/→ adjust · Enter confirm · Esc cancel · shift+tab cycles the plain levels";
-const SHORT_HINTS = "←/→ · Enter · Esc";
+const HINTS = "←/→ or h/l adjust · Enter confirm · Esc cancel · shift+tab cycles the plain levels";
+/** Anthropic's cache hierarchy: a thinking/effort change invalidates the message cache once (CACHE-REVIEW-2026-09-04 M4). */
+const CACHE_NOTE = "changing effort re-caches the conversation (one uncached request)";
+const SHORT_HINTS = "←/→ h/l · Enter · Esc";
 const ULTRACODE_SUBTITLE = `${ULTRACODE_LEVEL} + workflows`;
 
 /**
@@ -236,6 +253,7 @@ export function renderEffortSlider(view: SliderView, paint: Paint): string[] {
 	const anyDisabled = stops.some((_, i) => !view.enabled[i]);
 	const note = anyDisabled ? `dimmed = unsupported by ${view.modelLabel ?? "this model"}` : "";
 	if (note) rows.push([note, paint("dim", note)]);
+	rows.push([CACHE_NOTE, paint("dim", CACHE_NOTE)]);
 	rows.push(["", ""], [HINTS, paint("dim", HINTS)]);
 
 	const fits = rows.every(([plainRow]) => [...plainRow].length <= view.width);
@@ -251,3 +269,16 @@ export function renderEffortSlider(view: SliderView, paint: Paint): string[] {
 		paint("dim", clip(SHORT_HINTS)),
 	];
 }
+
+/**
+ * Claude Code's effort-changed note ("● high · /effort"), shown transiently
+ * right-aligned above the input after the level changes. Symbols are CC's
+ * (constants/figures.ts: ○ low, ◐ medium, ● high, ◉ max); pi's extra rungs
+ * map onto the nearest CC level, and ultracode keeps its own ✦ badge.
+ */
+export function effortNoteText(level: ThinkingLevel, ultracode: boolean): string {
+	if (ultracode) return "✦ ultracode · /effort";
+	const symbol =
+		level === "medium" ? "◐" : level === "high" ? "●" : level === "xhigh" || level === "max" ? "◉" : "○";
+	return `${symbol} ${level} · /effort`;
+}

package/extensions/file-tracker/index.ts

@@ -12,14 +12,29 @@
  * that went through bash and never touched an intercepted tool.
  */
 
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { isAbsolute, resolve } from "node:path";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { pathArgument } from "../auto-mode/paths.ts";
 import { REMINDER_CHANNEL } from "../lib/reminders.ts";
-import { describeChanges, EXTERNAL_CHANGE_REMINDER, FileTracker, STALE_REASON, UNREAD_REASON } from "./tracker.ts";
+import { pathsReadOnBranch } from "./replay.ts";
+import {
+	describeChanges,
+	EXTERNAL_CHANGE_REMINDER,
+	type FileStamp,
+	FileTracker,
+	STALE_REASON,
+	UNREAD_REASON,
+} from "./tracker.ts";
 
 const GUARDED_TOOLS = new Set(["edit", "write", "notebook_edit"]);
 const READ_TOOLS = new Set(["read", "notebook_edit"]);
+/**
+ * At most this many changed files get the full excerpt reminder per turn; the
+ * rest are named in one line. A formatter pass or `git checkout` touching
+ * dozens of tracked files otherwise produced dozens of 40-line blocks (review T8).
+ */
+const DETAILED_CHANGE_REMINDERS_PER_TURN = 5;
 
 function readIfPresent(path: string): string | undefined {
 	if (!existsSync(path)) return undefined;
@@ -31,14 +46,60 @@ function readIfPresent(path: string): string | undefined {
 	}
 }
 
+/** The file's disk stamp, or undefined when it is gone (or not a plain file we could stat). */
+function statIfPresent(path: string): FileStamp | undefined {
+	try {
+		const stat = statSync(path);
+		return { mtimeMs: stat.mtimeMs, size: stat.size };
+	} catch {
+		return undefined;
+	}
+}
+
+/** Observe a file's current content together with the stamp it was read at. */
+function observeFromDisk(tracker: FileTracker, path: string): void {
+	const stamp = statIfPresent(path);
+	const current = readIfPresent(path);
+	if (current === undefined) tracker.forget(path);
+	else tracker.observe(path, current, Date.now(), stamp);
+}
+
 function pathOf(input: unknown, cwd: string): string | undefined {
-	const raw = (input as { path?: unknown })?.path;
+	// Share the field-name knowledge with the auto-mode gates: `path` for pi's
+	// built-ins, `file_path`/`notebook_path` for Claude Code-shaped calls. A
+	// notebook_edit using only `notebook_path` would otherwise bypass the
+	// read-before-write guard (code-review).
+	const raw = pathArgument(input as Record<string, unknown> | undefined);
 	if (typeof raw !== "string" || !raw.trim()) return undefined;
 	return isAbsolute(raw) ? raw : resolve(cwd, raw);
 }
 
 export default function fileTrackerExtension(pi: ExtensionAPI) {
-	const tracker = new FileTracker();
+	let tracker = new FileTracker();
+	let sessionId: string | undefined;
+
+	// A resumed session (or a session_tree switch) carries reads the model did
+	// earlier in the transcript; rebuild the tracker from the branch so post-
+	// resume edits are not refused as "never read" (replay.ts). A new session id
+	// starts from an empty tracker.
+	const reconstruct = (ctx: ExtensionContext) => {
+		const id = ctx.sessionManager.getSessionId?.() ?? undefined;
+		if (id !== sessionId) {
+			sessionId = id;
+			tracker = new FileTracker();
+		}
+		let entries: unknown[] = [];
+		try {
+			entries = ctx.sessionManager.getBranch() as unknown[];
+		} catch {
+			return;
+		}
+		for (const raw of pathsReadOnBranch(entries)) {
+			observeFromDisk(tracker, isAbsolute(raw) ? raw : resolve(ctx.cwd, raw));
+		}
+	};
+	pi.on("session_start", (_event, ctx) => reconstruct(ctx));
+	pi.on("session_tree", (_event, ctx) => reconstruct(ctx));
 
 	pi.on("tool_call", (event, ctx) => {
 		if (!GUARDED_TOOLS.has(event.toolName)) return undefined;
@@ -63,41 +124,103 @@ export default function fileTrackerExtension(pi: ExtensionAPI) {
 
 		// After a read we know the file; after our own write we know it again, so a
 		// successful edit does not make the file look stale to the next edit.
-		const current = readIfPresent(path);
-		if (current === undefined) tracker.forget(path);
-		else tracker.observe(path, current, Date.now());
+		observeFromDisk(tracker, path);
 		return undefined;
 	});
 
 	/**
-	 * Before each turn, report anything that changed under us. Doing it here rather
-	 * than on a watcher keeps it deterministic and costs one stat+read per tracked
-	 * file, only for files the model actually touched.
+	 * Report anything that changed under us. Costs one stat per tracked file
+	 * (only files the model actually touched) and a read only for a file whose
+	 * stamp moved since we last read it; `alreadyNotified` keeps a repeat scan
+	 * from repeating a warning.
+	 *
+	 * Two triggers:
+	 * - `agent_start`, for changes made between turns. Not `before_agent_start`:
+	 *   pi emits that only from `prompt()`, so a run opened by a harness
+	 *   notification (a `/loop` tick, an agent report arriving while idle) never
+	 *   fired it and changes went unreported until the next user prompt
+	 *   (STEERING-REVIEW-2026-09-05 H1). `agent_start` fires for every run.
+	 * - `tool_execution_end`, for changes made DURING a turn — a formatter hook,
+	 *   a watcher, format-on-save in the user's editor, a `git checkout` by a
+	 *   background command. Until 2026-09-05 these waited for the next prompt;
+	 *   mid-turn the model discovered them only by hitting the stale-edit guard
+	 *   (one blocked call plus a re-read per edit for anyone with an asynchronous
+	 *   formatter). Claude Code computes its `edited_text_file` attachments on
+	 *   every tool round, so the model reads the change before its next edit
+	 *   (review M5). The one-shot is pending when the next request goes out and
+	 *   the injector pins it to that tool result — pi runs `tool_result` hooks
+	 *   BEFORE it emits `tool_execution_end` (agent-loop.js
+	 *   finalizeExecutedToolCall → emitToolExecutionEnd), so it cannot be written
+	 *   into the stored result; pinned is the same mechanism tool-search's
+	 *   deferred-tool miss uses. Our own edit/write/read of a file was observed by
+	 *   the `tool_result` handler above before this fires, so it is fresh here
+	 *   and never reported as external — but only for a call that ran alone. pi
+	 *   executes a batch of parallel tool calls CONCURRENTLY, so the first edit's
+	 *   end fires while a sibling edit has already written its file and not yet
+	 *   had its `tool_result` observation, and the scan reported the model's own
+	 *   edit as "modified by the user, a linter, or a command"
+	 *   (WEAK-MODEL-REVIEW-2026-09-06 M2). Hence `executing`: mid-turn the scan
+	 *   runs only once the batch has fully drained.
 	 */
-	pi.on("before_agent_start", () => {
+	const reportExternalChanges = () => {
+		const detailed: string[] = [];
+		const overflow: string[] = [];
 		for (const path of tracker.tracked) {
 			const previous = tracker.lastSeen(path);
 			if (previous === undefined || previous === "") continue;
-			const current = readIfPresent(path);
-			if (current === undefined) {
+			const stamp = statIfPresent(path);
+			if (stamp && tracker.unchangedOnDisk(path, stamp)) continue;
+			const current = stamp ? readIfPresent(path) : undefined;
+			if (stamp === undefined || current === undefined) {
 				tracker.forget(path);
-				pi.events.emit(REMINDER_CHANNEL, {
-					text: `${path} no longer exists; it was deleted or moved after you read it.`,
-				});
+				detailed.push(`${path} no longer exists; it was deleted or moved after you read it.`);
 				continue;
 			}
+			tracker.recordStamp(path, stamp);
 			if (current === previous) continue;
 			// Don't repeat the same warning every turn…
 			if (tracker.alreadyNotified(path, current)) continue;
 
-			const excerpt = describeChanges(previous, current);
-			if (excerpt) {
-				pi.events.emit(REMINDER_CHANNEL, { text: EXTERNAL_CHANGE_REMINDER(path, excerpt) });
+			if (detailed.length < DETAILED_CHANGE_REMINDERS_PER_TURN) {
+				const excerpt = describeChanges(previous, current);
+				if (excerpt) detailed.push(EXTERNAL_CHANGE_REMINDER(path, excerpt));
+			} else {
+				overflow.push(path);
 			}
 			// …but deliberately do NOT record the new content as seen: the file must
 			// stay stale so the edit guard still forces a re-read. Marking it read
 			// here would announce the change and then permit the clobbering edit.
 			tracker.markNotified(path, current);
 		}
+		for (const text of detailed) pi.events.emit(REMINDER_CHANNEL, { text });
+		if (overflow.length > 0) {
+			pi.events.emit(REMINDER_CHANNEL, {
+				text: `${overflow.length} more file(s) you read earlier changed on disk since: ${overflow.join(", ")}. Re-read any of them before editing it.`,
+			});
+		}
+	};
+	/**
+	 * Tool calls currently executing, by call id. A batch issued in one assistant
+	 * message runs concurrently, and only the last call to finish sees every
+	 * sibling's write already observed.
+	 */
+	const executing = new Set<string>();
+	pi.on("tool_execution_start", (event) => {
+		executing.add(event.toolCallId);
+		return undefined;
+	});
+	pi.on("agent_start", () => {
+		// A turn aborted mid-batch can leave ids behind; each turn starts from a
+		// clean set so the mid-turn scan cannot be wedged off for the rest of the
+		// session.
+		executing.clear();
+		reportExternalChanges();
+		return undefined;
+	});
+	pi.on("tool_execution_end", (event) => {
+		executing.delete(event.toolCallId);
+		if (executing.size > 0) return undefined;
+		reportExternalChanges();
+		return undefined;
 	});
 }

package/extensions/file-tracker/replay.ts

@@ -0,0 +1,46 @@
+/**
+ * Rebuild read-before-write state from a session branch (pure): which files
+ * the model has read or written this conversation, so a `--resume`d session
+ * does not block every edit with "has not been read in this conversation" —
+ * a claim the model can see is false in its own transcript (review T9).
+ *
+ * The content the model saw is not in the transcript, so a replayed file is
+ * observed with its CURRENT content: an edit after resume is allowed, and a
+ * change made while the session was closed is not flagged. That is Claude
+ * Code's behaviour too (its read state persists across resume); the stale-edit
+ * guard still catches anything that changes from this point on.
+ */
+
+const READ_TOOLS = new Set(["read", "notebook_edit"]);
+const WRITE_TOOLS = new Set(["edit", "write", "notebook_edit"]);
+
+interface ToolCallBlock {
+	type: "toolCall";
+	id: string;
+	name: string;
+	arguments?: Record<string, unknown>;
+}
+
+/** Paths (as written in the tool input) of every successful read/edit/write on the branch, in order, deduplicated. */
+export function pathsReadOnBranch(entries: unknown[]): string[] {
+	const calls = new Map<string, { name: string; path: string }>();
+	const seen: string[] = [];
+	for (const entry of entries) {
+		const e = entry as { type?: string; message?: { role?: string; content?: unknown; toolCallId?: string; toolName?: string; isError?: boolean } };
+		if (e?.type !== "message" || !e.message) continue;
+		const m = e.message;
+		if (m.role === "assistant" && Array.isArray(m.content)) {
+			for (const block of m.content as ToolCallBlock[]) {
+				if (block?.type !== "toolCall" || !block.id) continue;
+				const path = block.arguments?.path;
+				if (typeof path === "string" && path.trim()) calls.set(block.id, { name: block.name, path });
+			}
+		} else if (m.role === "toolResult" && m.toolCallId && !m.isError) {
+			const call = calls.get(m.toolCallId);
+			if (!call) continue;
+			if (!READ_TOOLS.has(call.name) && !WRITE_TOOLS.has(call.name)) continue;
+			if (!seen.includes(call.path)) seen.push(call.path);
+		}
+	}
+	return seen;
+}

package/extensions/file-tracker/tracker.ts

@@ -18,12 +18,28 @@ export interface TrackedFile {
 	at: number;
 }
 
+/** What a stat says about a file on disk; equal stamps mean "no need to re-read". */
+export interface FileStamp {
+	mtimeMs: number;
+	size: number;
+}
+
 /** Keeps memory bounded on long sessions with large files. */
 const MAX_TRACKED_FILES = 300;
 const MAX_TRACKED_BYTES = 512 * 1024;
+/** Stamps younger than this are re-read regardless (coarse-mtime filesystems, same-tick rewrites). */
+export const RACY_STAMP_MS = 2000;
 
 export class FileTracker {
 	private files = new Map<string, TrackedFile>();
+	/**
+	 * The disk stamp of the content last compared per path — recorded when we
+	 * observe a file and again each time the change scan reads it. The scan runs
+	 * after every tool call, so a full read of every tracked file each time would
+	 * cost up to 300 reads per call; a stat per file and a read only when the
+	 * stamp moved keeps the common "nothing changed" case cheap.
+	 */
+	private stamps = new Map<string, FileStamp>();
 	/**
 	 * Content we have already warned about, per path. Kept separate from `files`
 	 * because telling the model a file changed must NOT make the file count as
@@ -33,8 +49,8 @@ export class FileTracker {
 	 */
 	private notified = new Map<string, string>();
 
-	/** Record what we currently believe a file contains (after a read or a write). */
-	observe(path: string, content: string, at: number): void {
+	/** Record what we currently believe a file contains (after a read or a write), and its disk stamp when known. */
+	observe(path: string, content: string, at: number, stamp?: FileStamp): void {
 		this.notified.delete(path);
 		if (content.length > MAX_TRACKED_BYTES) {
 			// Too large to diff usefully; remember that we saw it, not its content.
@@ -42,15 +58,36 @@ export class FileTracker {
 		} else {
 			this.files.set(path, { content, at });
 		}
+		if (stamp) this.stamps.set(path, stamp);
+		else this.stamps.delete(path);
 		if (this.files.size > MAX_TRACKED_FILES) {
 			const oldest = [...this.files.entries()].sort((a, b) => a[1].at - b[1].at)[0];
-			if (oldest) this.files.delete(oldest[0]);
+			if (oldest) this.forget(oldest[0]);
 		}
 	}
 
 	forget(path: string): void {
 		this.files.delete(path);
 		this.notified.delete(path);
+		this.stamps.delete(path);
+	}
+
+	/**
+	 * True when the disk stamp matches the one recorded at the last read of this
+	 * path: nothing to re-read. A stamp younger than `RACY_STAMP_MS` is never
+	 * trusted: a same-size rewrite within the filesystem's mtime granularity of
+	 * our read would leave the stamp unchanged (git's "racy" rule), so recent
+	 * files take the full read until they age past the window.
+	 */
+	unchangedOnDisk(path: string, stamp: FileStamp, now = Date.now()): boolean {
+		if (now - stamp.mtimeMs < RACY_STAMP_MS) return false;
+		const known = this.stamps.get(path);
+		return known !== undefined && known.mtimeMs === stamp.mtimeMs && known.size === stamp.size;
+	}
+
+	/** The change scan read the file at this stamp; the next scan skips it until the stamp moves. */
+	recordStamp(path: string, stamp: FileStamp): void {
+		this.stamps.set(path, stamp);
 	}
 
 	/** True when this exact content has already been reported for this path. */
@@ -141,5 +178,15 @@ export const UNREAD_REASON = (path: string, tool: string) =>
 export const STALE_REASON = (path: string) =>
 	`${path} has changed on disk since you last read it — someone else, a formatter, or a command may have modified it. Read it again before editing, or your change would overwrite theirs.`;
 
+/**
+ * Claude Code's `edited_text_file` attachment text, with two additions: the
+ * cause list also names a command (our tracker sees bash writes too), and the
+ * closing clause tells the model to re-read before editing — CC marks the file
+ * as read when it attaches the snippet, we deliberately do not (the stale-edit
+ * guard keeps firing), so without that clause the model's next edit is blocked
+ * and costs a round trip. The "intentional / don't revert / don't tell the
+ * user" steer is CC's: without it a model mid-edit tends to restore its own
+ * version and narrate linter noise (STEERING-REVIEW-2026-09-05 M5).
+ */
 export const EXTERNAL_CHANGE_REMINDER = (path: string, excerpt: ChangeExcerpt) =>
-	`${path} was modified externally (by the user, a formatter, or a command) after you last read it. The file now reads as follows around the change (line numbers shown); re-read it if you need the full contents.\n\n${excerpt.text}`;
+	`Note: ${path} was modified, either by the user, a linter, or a command, after you last read it. This change was intentional, so make sure to take it into account as you proceed (ie. don't revert it unless the user asks you to). Don't tell the user this, since they are already aware. Here are the relevant changes (shown with line numbers); re-read the file before editing it:\n${excerpt.text}`;