one-code-extension 0.4.1 → 0.6.0

package/extensions/file-tracker/replay.ts

@@ -1,18 +1,26 @@
 /**
  * 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 model has seen 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.
+ * The content the model saw is not in the transcript, but each read and write
+ * result records what it saw (`details.oneCodeFile`, `FileObservation`) under
+ * the absolute path the tool resolved. The replay keys on that path, never on
+ * the call's own spelling: a worktree rewrites a relative path only in the
+ * call it runs, so the transcript's `a.ts` would resolve to the main
+ * checkout's twin (round-3 review M15). A post-compaction restore records the
+ * same on its pending entry, and a changed-on-disk notice records the
+ * versions it named. The caller compares each observation with the disk: a
+ * file that still matches is read, one that changed since is stale. A result
+ * that recorded nothing (a session from before the record existed) leaves its
+ * file unread: the disk as it is now is never taken as what the model saw
+ * (round-2 review H1).
  */
 
-const READ_TOOLS = new Set(["read", "notebook_edit"]);
-const WRITE_TOOLS = new Set(["edit", "write", "notebook_edit"]);
+import { latestCompaction } from "../lib/compaction-boundary.ts";
+import { type FileVersion, isFileVersion, readRecord } from "../lib/ledger/records.ts";
+import { shownInFull } from "./shell-reads.ts";
 
 interface ToolCallBlock {
 	type: "toolCall";
@@ -21,26 +29,131 @@ interface ToolCallBlock {
 	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[] = [];
+type BranchMessage = { role?: string; content?: unknown; toolCallId?: string; toolName?: string; isError?: boolean; details?: { oneCodeFile?: unknown } };
+
+/** What a read or write result saw of its file, recorded in its details as `oneCodeFile`: a version with its size and modification time. */
+export type FileObservation = Required<FileVersion>;
+
+const isObservation = (value: unknown): value is FileObservation => isFileVersion(value) && value.size !== undefined && value.mtimeMs !== undefined;
+
+/**
+ * Every successful tool result on the branch that recorded what it saw of a
+ * file, in branch order: its position, the tool that ran (from its call, else
+ * the result's own `toolName`) and the observation.
+ */
+function* fileResults(entries: readonly unknown[]): Generator<{ index: number; name: string | undefined; seen: FileObservation }> {
+	const names = new Map<string, string>();
+	for (const [index, entry] of entries.entries()) {
+		const e = entry as { type?: string; message?: BranchMessage };
+		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) names.set(block.id, block.name);
+		} else if (m.role === "toolResult" && !m.isError) {
+			const seen = m.details?.oneCodeFile;
+			if (isObservation(seen)) yield { index, name: (m.toolCallId ? names.get(m.toolCallId) : undefined) ?? m.toolName, seen };
+		}
+	}
+}
+
+/** What the branch shows the model saw of a file, and what it was told about the file since. */
+export interface SeenFile {
+	/** The version the model last saw, as the result or restore that showed it recorded it. */
+	seen: FileObservation;
+	/** Content hashes of the changed versions a notice named after that. */
+	notified: Set<string>;
+}
+
+/**
+ * Each file the model saw in the entries still in context (`inContextEntries`),
+ * by absolute path: the last result or post-compaction restore that showed
+ * it, and the changed versions a notice named since.
+ *
+ * In the kept turns before the latest compaction a `read` result counts, as
+ * at the compaction itself: a kept edit or write does not show the whole
+ * file, so it counts only for a file a kept read showed before it, where it
+ * records the version the edit left (the live tracker observes the file
+ * again after its own write, and the compaction keeps that). A restore counts only after the latest compaction, and there it
+ * counts whether or not a request delivered it yet. A later compaction is
+ * the only thing that drops a restore undelivered (lib/ledger/fold.ts), so
+ * one recorded since the latest is either delivered or rides the next
+ * request, and the model sees the file before it can call a tool on it; the
+ * live session counts it read from the compaction on, too. A notice counts
+ * wherever it lies after the file's last observation: it is delivered or
+ * pending, and announcing the same version again would repeat it.
+ */
+export function filesSeenOnBranch(entries: readonly unknown[]): Map<string, SeenFile> {
+	const compaction = latestCompaction(entries)?.index ?? -1;
+	const results = new Map([...fileResults(entries)].map((result) => [result.index, result]));
+	const files = new Map<string, SeenFile>();
+	const see = (seen: FileObservation) => files.set(seen.path, { seen, notified: new Set() });
+	entries.forEach((entry, index) => {
+		const result = results.get(index);
+		if (result) {
+			if (index > compaction || result.name === "read" || files.has(result.seen.path)) see(result.seen);
+			return;
+		}
+		const record = readRecord(entry as never);
+		if (record?.kind !== "pending") return;
+		if (index > compaction) for (const seen of record.data.observations ?? []) if (isObservation(seen)) see(seen);
+		for (const told of record.data.notified ?? []) files.get(told.path)?.notified.add(told.sha256);
+	});
+	return files;
+}
+
+/**
+ * The files (absolute, as their results recorded them) that a successful
+ * `read` in the kept turns returned: those files are in context already, so
+ * the post-compaction restore skips them.
+ */
+export function keptReadPaths(kept: readonly unknown[]): string[] {
+	return [...fileResults(kept)].filter((result) => result.name === "read").map((result) => result.seen.path);
+}
+
+/**
+ * The tracked files that a bash call in the kept turns showed in full: those
+ * the call certified when it ran (`readsOf`, by call id: the directory it ran
+ * in decided, never today's) whose content as the tracker last saw it (`seen`)
+ * is still all in its kept output. Like a kept `read`, they are in context
+ * still, so they stay read; a file changed since is then stale, not unread. A
+ * call needs its result in the kept turns too, and one with no record
+ * certifies nothing (a miss costs one re-read).
+ */
+export function keptShellReadPaths(kept: readonly unknown[], readsOf: (callId: string) => readonly string[] | undefined, seen: (path: string) => string | undefined): string[] {
+	const shown = new Set<string>();
+	for (const { id, output } of shellCallsOnBranch(kept)) {
+		for (const path of readsOf(id) ?? []) {
+			if (shown.has(path)) continue;
+			const content = seen(path);
+			if (content !== undefined && shownInFull(output, content)) shown.add(path);
+		}
+	}
+	return [...shown];
+}
+
+/**
+ * Every bash call on the branch with its command and the text of its result,
+ * in result order: a resumed session re-checks which files those outputs
+ * showed in full (`shell-reads.ts`), against the files' current content.
+ */
+export function* shellCallsOnBranch(entries: readonly unknown[]): Generator<{ id: string; command: string; output: string }> {
+	const commands = new Map<string, string>();
 	for (const entry of entries) {
-		const e = entry as { type?: string; message?: { role?: string; content?: unknown; toolCallId?: string; toolName?: string; isError?: boolean } };
+		const e = entry as { type?: string; message?: BranchMessage };
 		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 });
+				const command = block?.type === "toolCall" && block.name === "bash" ? block.arguments?.command : undefined;
+				if (typeof command === "string" && block.id) commands.set(block.id, command);
 			}
-		} 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);
+		} else if (m.role === "toolResult" && m.toolCallId) {
+			const command = commands.get(m.toolCallId);
+			if (command === undefined || !Array.isArray(m.content)) continue;
+			const output = (m.content as { type?: string; text?: string }[])
+				.map((block) => (block?.type === "text" ? (block.text ?? "") : ""))
+				.join("\n");
+			yield { id: m.toolCallId, command, output };
 		}
 	}
-	return seen;
 }

package/extensions/file-tracker/restore.ts

@@ -0,0 +1,66 @@
+/**
+ * The files that come back after a compaction, and how. Pure: no pi imports,
+ * no I/O.
+ *
+ * As in Claude Code: the five files the session read, edited or wrote with
+ * the newest modification time (as stat'ed at that read or write), minus the
+ * files the context still shows, are read again. A file within 5,000 tokens
+ * comes back as a read call and its result, a larger one as a note to read it
+ * again, while the total stays within 50,000 tokens (findings §47). Each is
+ * its own `<system-reminder>` block at the start of the next user message,
+ * worded as Claude Code words them with One Code's tool name and argument
+ * (`read`, `path`).
+ */
+
+export const RESTORE_MAX_FILES = 5;
+export const RESTORE_FILE_MAX_TOKENS = 5_000;
+export const RESTORE_TOTAL_MAX_TOKENS = 50_000;
+
+/**
+ * The files to restore, newest first: the touched files (path to modification
+ * time) minus `skip`, at most five. A file that cannot be read again is
+ * dropped afterwards, not replaced, as in Claude Code.
+ */
+export function restoreCandidates(touched: ReadonlyMap<string, number>, skip: (path: string) => boolean): string[] {
+	const candidates: string[] = [];
+	for (const [path] of [...touched].sort((a, b) => b[1] - a[1])) {
+		if (candidates.length === RESTORE_MAX_FILES) break;
+		if (!skip(path)) candidates.push(path);
+	}
+	return candidates;
+}
+
+/** What reading a candidate again gave: its text as the read tool returns it, or nothing (gone, unreadable, an image). */
+export type RestoredRead = { path: string; text: string | undefined };
+
+/** One `<system-reminder>` block of a restore; `restores` names the file whose contents it puts back in context. */
+export type RestoreBlock = { text: string; restores?: string };
+
+/**
+ * The reminder blocks for the reads, in order: two blocks for a file within
+ * the per-file cap (the result block `restores` it), one note for a larger
+ * one, nothing for a file that could not be read. A file's blocks are kept
+ * only while the running total stays within the overall cap. `restored` lists
+ * the files whose contents went back into context.
+ */
+export function restoreBlocks(reads: RestoredRead[], estimateTokens: (text: string) => number): { blocks: RestoreBlock[]; restored: string[] } {
+	const blocks: RestoreBlock[] = [];
+	const restored: string[] = [];
+	let total = 0;
+	for (const { path, text } of reads) {
+		if (text === undefined) continue;
+		const fits = estimateTokens(text) <= RESTORE_FILE_MAX_TOKENS;
+		const fileBlocks: RestoreBlock[] = fits ? [{ text: readCallBlock(path) }, { text: readResultBlock(text), restores: path }] : [{ text: tooLargeNote(path) }];
+		const tokens = fileBlocks.reduce((sum, block) => sum + estimateTokens(block.text), 0);
+		if (total + tokens > RESTORE_TOTAL_MAX_TOKENS) continue;
+		total += tokens;
+		blocks.push(...fileBlocks);
+		if (fits) restored.push(path);
+	}
+	return { blocks, restored };
+}
+
+export const readCallBlock = (path: string) => `Called the read tool with the following input: ${JSON.stringify({ path })}`;
+export const readResultBlock = (text: string) => `Result of calling the read tool:\n${text}`;
+export const tooLargeNote = (path: string) =>
+	`Note: ${path} was read before the last conversation was summarized, but the contents are too large to include. Use read tool if you need to access it.`;

package/extensions/file-tracker/results.ts

@@ -0,0 +1,66 @@
+/**
+ * Claude Code's result and error texts for pi's built-in read, write and edit
+ * (pure). pi's tools keep their call shapes (`path`, `edits[]`) and their own
+ * behavior; only what the model reads back changes, by rewriting the first
+ * text block of a result whose text is pi's exact wording. Anything else
+ * (pi's truncation notes, an image, a block another hook appended) passes
+ * through untouched.
+ *
+ * The success texts say the file state is current, which is true here: the
+ * file-tracker observes the file after every successful write or edit, so the
+ * next edit is not refused as unread or stale.
+ */
+
+type Block = { type: string; text?: string };
+
+export const FILE_STATE_CURRENT = " (file state is current in your context — no need to read it back)";
+
+/** Claude Code's missing-file error for read and edit. */
+export function fileDoesNotExist(cwd: string): string {
+	return `File does not exist. Note: your current working directory is ${cwd}.`;
+}
+
+/** Claude Code's empty-file read result. */
+export const EMPTY_FILE_WARNING = "<system-reminder>Warning: the file exists but the contents are empty.</system-reminder>";
+
+export interface FileToolResult {
+	toolName: string;
+	isError: boolean;
+	content: Block[];
+	/** The absolute path the tool touched. */
+	path: string;
+	cwd: string;
+	/** For a write: whether the file existed before the call (Claude Code says "updated" then, "created" otherwise). */
+	existedBefore?: boolean;
+	/** For a read: whether the file is empty on disk (asked only for an empty result). */
+	isEmptyFile?: () => boolean;
+}
+
+/** The first block's replacement text, or undefined to leave the result as pi wrote it. */
+function rewrite(result: FileToolResult, text: string): string | undefined {
+	const { toolName, isError, path, cwd } = result;
+	if (toolName === "write" && !isError && text.startsWith("Successfully wrote to ")) {
+		return result.existedBefore
+			? `The file ${path} has been updated successfully.${FILE_STATE_CURRENT}`
+			: `File created successfully at: ${path}${FILE_STATE_CURRENT}`;
+	}
+	if (toolName === "edit" && !isError && /^Successfully replaced \d+ block\(s\) in /.test(text)) {
+		return `The file ${path} has been updated successfully.${FILE_STATE_CURRENT}`;
+	}
+	if (toolName === "edit" && isError && /^Could not edit file: .*\. Error code: ENOENT\.$/s.test(text)) return fileDoesNotExist(cwd);
+	if (toolName === "read" && isError) {
+		if (/^ENOENT: no such file or directory, \w+ '/.test(text)) return fileDoesNotExist(cwd);
+		if (text === "EISDIR: illegal operation on a directory, read") return `${text} '${path}'`;
+	}
+	if (toolName === "read" && !isError && text === "" && result.isEmptyFile?.()) return EMPTY_FILE_WARNING;
+	return undefined;
+}
+
+/** The result's content with Claude Code's text in place of pi's, or undefined when nothing changes. */
+export function fileToolResultContent<B extends Block>(result: FileToolResult & { content: B[] }): B[] | undefined {
+	if (!Array.isArray(result.content)) return undefined;
+	const [first, ...rest] = result.content;
+	if (first?.type !== "text" || typeof first.text !== "string") return undefined;
+	const text = rewrite(result, first.text);
+	return text === undefined ? undefined : [{ ...first, text }, ...rest];
+}

package/extensions/file-tracker/shell-reads.ts

@@ -0,0 +1,211 @@
+/**
+ * Files a shell command showed the model in full (pure apart from the bash
+ * grammar, which the caller awaits).
+ *
+ * The auto-mode note tells the model to read files with cat, head or sed, and
+ * GPT-6 models do. Before this, the edit that followed was refused as
+ * "not read in this conversation" although the whole file was in the
+ * transcript: 16 refused edits in one 72-run battery (2026-10-04). A file now
+ * counts as read when a line that runs a reader names it and the output holds
+ * the file's entire current content. That one check covers every way the
+ * model could have seen less: a pipe into `head`, `cat -n`, a slice, an output
+ * persisted or clipped for size, a write later in the same command. The
+ * stale-edit guard is unchanged, since the file is observed with that content.
+ */
+
+import { isAbsolute } from "node:path";
+import { toAbsoluteBash } from "../auto-mode/paths.ts";
+import { globComponentRegex, isUnknownTilde, movesDirectory, resolvePayload } from "../auto-mode/shell-analysis.ts";
+import { LOOPS, parseCommand, type ParseResult, scopedTracker, type Segment, type Token } from "../auto-mode/shell-parse.ts";
+
+/** Commands whose file arguments may print a whole file. */
+const READERS = new Set(["cat", "head", "tail", "sed"]);
+
+const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+
+/** A word a reader may have printed, with the absolute directory the shell resolves it in. */
+export interface ShellReadCandidate {
+	word: string;
+	dir: string;
+}
+
+/**
+ * The files `command` may have printed, as written: the plain arguments of
+ * its reader commands, plus every path-like word of a line that runs a reader
+ * at all. Candidates only, each still to be checked with {@link shownInFull}.
+ * Each comes with the directory its reader runs in, starting from `cwd` and
+ * following a literal `cd` ({@link segmentDirectories}); a reader whose
+ * directory cannot be known offers nothing. Empty when no reader runs or the
+ * command does not parse (the grammar not loaded included).
+ */
+export function shellReadCandidates(command: string, cwd: string, home: string): ShellReadCandidate[] {
+	const parsed = parseCommand(command);
+	if (parsed.parseFailed) return [];
+	const readers = parsed.segments.flatMap((segment, index) => {
+		const first = segment.tokens.findIndex((token) => !ASSIGNMENT.test(token.value));
+		if (first === -1) return [];
+		const [head, ...args] = segment.tokens.slice(first);
+		return head && !head.dynamic && READERS.has(head.value.split("/").pop() ?? "") ? [{ segment, index, args }] : [];
+	});
+	// Most commands run no reader: skip the directory walk for them.
+	if (readers.length === 0) return [];
+	const dirs = segmentDirectories(parsed, cwd, home);
+	const candidates = new Map<string, ShellReadCandidate>();
+	const add = (word: string, dir: string) => candidates.set(`${dir}\0${word}`, { word, dir });
+	const readerDirs = new Set<string>();
+	for (const { segment, index, args } of readers) {
+		const dir = dirs[index];
+		if (dir === undefined) continue;
+		readerDirs.add(dir);
+		if (segment.substitution !== undefined) continue;
+		for (const arg of args) if (isPlainPath(arg)) add(arg.value, dir);
+	}
+	// A reader fed from a variable (`for f in a.py b.py; do cat "$f"; done`)
+	// names its files elsewhere in the line. Every plain path-like word is a
+	// candidate then, in each directory a reader ran in: the full-content
+	// check, not the parse, decides.
+	if (readerDirs.size > 0) {
+		const words = new Set<string>();
+		for (const word of [...(command.match(PATH_WORD) ?? []), ...(command.match(GLOB_WORD) ?? [])]) if (words.size < MAX_CANDIDATES) words.add(word);
+		for (const dir of [...readerDirs].slice(0, MAX_READER_DIRS)) for (const word of words) add(word, dir);
+	}
+	return [...candidates.values()];
+}
+
+/**
+ * The absolute paths `command` may have printed: its candidates
+ * ({@link shellReadCandidates}) resolved as the shell resolves them, from
+ * the directory each one's reader runs in, with a glob expanded through
+ * `readdir` (given an absolute directory). The shell's own resolution
+ * (`toAbsoluteBash`), not the file tools' (`resolveToolPath` strips a leading
+ * `@`, which `cat @x` keeps): `~/` and the shell's directory only.
+ */
+export function shellReadPaths(command: string, cwd: string, home: string, readdir: (dir: string) => string[]): string[] {
+	const paths = new Set<string>();
+	for (const { word, dir } of shellReadCandidates(command, cwd, home)) {
+		for (const name of expandCandidate(word, (sub) => readdir(toAbsoluteBash(dir, sub, home)))) paths.add(toAbsoluteBash(dir, name, home));
+	}
+	return [...paths];
+}
+
+/**
+ * The directory each segment runs in, or undefined where it cannot be known.
+ * Only a plain `cd <literal>` (or `cd -- <literal>`) that surely ran moves
+ * the commands after it in its own subshell scope (`scopedTracker`). One that
+ * may not run moves only the later members of its own `&&` list
+ * (`Segment.andList`), which run only once it succeeded (`cd src && cat x`
+ * inside the worktree's `cd <wt> && ( … )`). Anything else that may change
+ * the directory makes the commands after it unknown, never guessed: a
+ * dynamic, glob, `-` or `~user` target, an option, `pushd` and `popd`, a
+ * wrapper, assignment or `!` in front, a `cd` that may not run (an `if`
+ * branch, after `||`) for everything outside its `&&` list, a `cd` last in a
+ * pipeline (`lastpipe` runs it in the shell around), a backgrounded line,
+ * `eval` and `source`, and a line that defines a function (which may replace
+ * `cd`). A loop body runs more than once, so after a move in any loop every
+ * command in a loop is unknown too. A miss costs one re-read; a wrong
+ * directory would certify a read that never happened.
+ */
+function segmentDirectories(parsed: ParseResult, cwd: string, home: string): (string | undefined)[] {
+	const { segments } = parsed;
+	const dirs = scopedTracker<string | undefined>(cwd);
+	/** Where a `cd` that may not have run moved the later members of its `&&` list, by list. */
+	const listDirs = new Map<number, string | undefined>();
+	const inLoop = (segment: Segment) => segment.enclosing.some((construct) => LOOPS.has(construct));
+	const moves = segments.map(mayMove);
+	const loopMoves = segments.some((segment, index) => moves[index] && inLoop(segment));
+	return segments.map((segment, index) => {
+		const inList = segment.andList !== undefined && listDirs.has(segment.andList);
+		const dir = loopMoves && inLoop(segment) ? undefined : inList ? listDirs.get(segment.andList!) : dirs.get(segment);
+		if (!moves[index]) return dir;
+		const certain = !parsed.background && !parsed.definesFunction && !segment.pipelineShell && !segment.enclosing.includes("negated_command");
+		const target = certain ? literalCdTarget(segment) : undefined;
+		// A relative target from an unknown directory stays unknown; an absolute one re-anchors.
+		const next = target === undefined ? undefined : dir === undefined && !isAbsoluteTarget(target) ? undefined : toAbsoluteBash(dir ?? cwd, target, home);
+		if (segment.pipelineShell) dirs.set({ scopes: segment.pipelineShell }, undefined);
+		if (segment.conditional) {
+			dirs.set(segment, undefined);
+			if (segment.andList !== undefined) listDirs.set(segment.andList, next);
+		} else {
+			dirs.set(segment, next);
+		}
+		return dir;
+	});
+}
+
+/** Whether a segment may change the shell's directory: a `cd`/`pushd`/`popd` in any spelling, or a script run in this shell. */
+function mayMove(segment: Segment): boolean {
+	return movesDirectory(segment) || ["eval", "source", "."].includes(resolvePayload(segment.tokens).command);
+}
+
+/** The target of `cd <word>` or `cd -- <word>` written plainly, or undefined for any other form. */
+function literalCdTarget(segment: Segment): string | undefined {
+	const [head, ...args] = segment.tokens;
+	if (head?.value !== "cd" || head.dynamic) return undefined;
+	const rest = args[0]?.value === "--" ? args.slice(1) : args;
+	if (rest.length > 1) return undefined;
+	const target = rest[0];
+	// A bare `cd` goes home.
+	if (!target) return "~";
+	if (target.dynamic || target.glob || target.value === "" || target.value.startsWith("-") || isUnknownTilde(target.value)) return undefined;
+	return target.value;
+}
+
+/** Whether a `cd` target lands in the same place from any directory. */
+function isAbsoluteTarget(target: string): boolean {
+	return isAbsolute(target) || target === "~" || target.startsWith("~/");
+}
+
+/**
+ * The files a candidate names: itself, or for a glob in its last component
+ * (`src/*.py`, a loop's word list), the matching entries of that directory,
+ * listed through `readdir` (no shell). Globs in a directory component are not
+ * expanded.
+ */
+export function expandCandidate(word: string, readdir: (dir: string) => string[]): string[] {
+	if (!/[*?[]/.test(word)) return [word];
+	const slash = word.lastIndexOf("/");
+	const dir = slash === -1 ? "" : word.slice(0, slash);
+	if (/[*?[]/.test(dir)) return [];
+	const pattern = globComponentRegex(word.slice(slash + 1));
+	if (!pattern) return [];
+	let names: string[];
+	try {
+		names = readdir(dir || ".");
+	} catch {
+		return [];
+	}
+	return names.filter((name) => !name.startsWith(".") && pattern.test(name)).map((name) => (dir ? `${dir}/${name}` : name)).slice(0, MAX_CANDIDATES);
+}
+
+/** A word that could be a file path as written, absolute or relative: no quoting, expansion or glob characters. */
+const PATH_WORD = /(?<![\w$\-/])\/?[\w.@+~][\w.@+~/,-]*/g;
+/** A word with a glob character, which the shell would expand (`src/*.py`). */
+const GLOB_WORD = /(?<![\w$\-])[\w.@+~/,-]*[*?[][\w.@+~/,*?[\]-]*/g;
+const MAX_CANDIDATES = 50;
+/** The path-like words of a line are tried in at most this many reader directories. */
+const MAX_READER_DIRS = 4;
+
+function isPlainPath(token: Token): boolean {
+	return !token.dynamic && !token.glob && token.value !== "" && !token.value.startsWith("-");
+}
+
+/**
+ * Whether `output` shows the whole of `content`. Trailing whitespace is
+ * ignored because the shell tool trims it. A tiny one-line file is never
+ * counted: its text turns up in outputs by chance (an adversarial GPT-6 Astra
+ * run matched `completed` to "(bash completed with no output)", `1` to
+ * "Exit code 1", an error line, a persisted-output tag), so the match would
+ * not show that the file was printed. What the guard protects still holds for
+ * a larger match under another file's name: every byte of the file was in
+ * front of the model, so an edit cannot discard content it has not seen.
+ */
+export function shownInFull(output: string, content: string): boolean {
+	const body = content.trimEnd();
+	if (body.length < MIN_SHOWN_CHARS && !(body.includes("\n") && body.length >= MIN_SHOWN_LINES_CHARS)) return false;
+	return output.includes(body);
+}
+
+/** A one-line file shorter than this is never counted as shown. */
+const MIN_SHOWN_CHARS = 40;
+/** A multi-line file shorter than this is never counted as shown. */
+const MIN_SHOWN_LINES_CHARS = 16;

package/extensions/file-tracker/tracker.ts

@@ -13,9 +13,18 @@
 export type FreshnessStatus = "fresh" | "unread" | "stale" | "absent";
 
 export interface TrackedFile {
-	/** Content as of the last read or write we performed. */
+	/** Content as of the last read or write we performed ("" when `oversized`). */
 	content: string;
+	/**
+	 * Too large to keep: we saw the file but hold no content to compare. An
+	 * explicit flag, never the empty string, so a file read while EMPTY
+	 * compares like any other and cannot be overwritten after someone fills
+	 * it (TOOLS-REVIEW-2026-09-26 M2).
+	 */
+	oversized: boolean;
 	at: number;
+	/** Seen, but changed on disk since (a resumed read whose file moved on): stale until read again. */
+	changed?: boolean;
 }
 
 /** What a stat says about a file on disk; equal stamps mean "no need to re-read". */
@@ -54,9 +63,9 @@ export class FileTracker {
 		this.notified.delete(path);
 		if (content.length > MAX_TRACKED_BYTES) {
 			// Too large to diff usefully; remember that we saw it, not its content.
-			this.files.set(path, { content: "", at });
+			this.files.set(path, { content: "", oversized: true, at });
 		} else {
-			this.files.set(path, { content, at });
+			this.files.set(path, { content, oversized: false, at });
 		}
 		if (stamp) this.stamps.set(path, stamp);
 		else this.stamps.delete(path);
@@ -66,6 +75,16 @@ export class FileTracker {
 		}
 	}
 
+	/**
+	 * Record a file the model saw in a form that is gone: it changed on disk
+	 * since, and its old content is not kept. It counts as read, but stale.
+	 */
+	observeChanged(path: string, at: number): void {
+		this.notified.delete(path);
+		this.stamps.delete(path);
+		this.files.set(path, { content: "", oversized: false, at, changed: true });
+	}
+
 	forget(path: string): void {
 		this.files.delete(path);
 		this.notified.delete(path);
@@ -103,8 +122,10 @@ export class FileTracker {
 		return this.files.has(path);
 	}
 
+	/** The content last seen, or undefined when untracked or tracked without content (oversized). */
 	lastSeen(path: string): string | undefined {
-		return this.files.get(path)?.content;
+		const known = this.files.get(path);
+		return known && !known.oversized && !known.changed ? known.content : undefined;
 	}
 
 	get tracked(): string[] {
@@ -121,9 +142,10 @@ export class FileTracker {
 		if (currentContent === undefined) return "absent";
 		const known = this.files.get(path);
 		if (!known) return "unread";
+		if (known.changed) return "stale";
 		// Oversized files are tracked without content; treat them as fresh rather
 		// than blocking edits we cannot reason about.
-		if (known.content === "" && currentContent !== "") return "fresh";
+		if (known.oversized) return "fresh";
 		return known.content === currentContent ? "fresh" : "stale";
 	}
 }
@@ -173,20 +195,28 @@ export function describeChanges(
 }
 
 export const UNREAD_REASON = (path: string, tool: string) =>
-	`Read ${path} before using ${tool} on it. The file exists and has not been read in this conversation, so an edit could silently discard content you have not seen.`;
+	`Read ${path} before using ${tool} on it. The file exists and has not been read in this conversation, so an edit could silently discard content you have not seen. A shell read counts only when it printed the whole file as it is on disk (a plain \`cat\`); after a partial one (head, sed -n, a pipe, or output cut off at the size limit) or another version of it (such as \`git show HEAD:<file>\`), use the read tool.`;
+
+/**
+ * The same notice when one of this session's subagents or workflow agents
+ * changed the file (lib/child-writes.ts): saying "someone else, a formatter or
+ * a command" there sent the model looking for an outside cause.
+ */
+export const CHILD_CHANGE_REMINDER = (path: string, agent: string | undefined, excerpt: ChangeExcerpt) =>
+	`Note: ${path} was changed by ${agent ? `the agent "${agent}"` : "an agent"} you started in this session since you last read it. Take it as the current state. Here are the relevant changes (shown with line numbers); re-read the file before editing it:\n${excerpt.text}`;
 
 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).
+ * Claude Code's `edited_text_file` attachment text, plus One Code's closing
+ * clause telling the model to re-read before editing: Claude Code 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 "take it as the current state
+ * rather than reverting it" steer is Claude Code'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) =>
-	`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}`;
+	`Note: ${path} changed on disk since you last read it. That's usually deliberate, so take it as the current state rather than reverting it; if the change looks wrong, say so rather than undoing it yourself — otherwise no need to call it out. Here are the relevant changes (shown with line numbers); re-read the file before editing it:\n${excerpt.text}`;