one-code-extension 0.1.3 → 0.3.0

package/extensions/footer/footer-line.ts

@@ -0,0 +1,207 @@
+/**
+ * Pure formatting for the One Code footer — the single status line that
+ * replaces pi's built-in footer (`ctx.ui.setFooter`). It surfaces what a user
+ * actually watches — context fill, total cost, cache-hit health, the PR, the
+ * model, and the effort level — and drops pi's raw ↑/↓/R/W token counters.
+ *
+ * Everything here is pure and paint-injected so it unit-tests with an identity
+ * paint. `paint(color, text)` matches `safeThemePaint`; in tests it returns the
+ * text unchanged, so assertions see the plain line. Inclusion decisions use
+ * plain lengths only, so the painted result (ANSI adds zero display width)
+ * always fits the width it was built for.
+ */
+
+import { costOf, usageEntryCost } from "../lib/usage-bus.ts";
+
+export type Paint = (color: string, text: string) => string;
+
+export interface FooterData {
+	/** Absolute cwd; `home` is folded to `~` for display. */
+	cwd: string;
+	home: string;
+	branch?: string;
+	/** Context tokens in use and the model's window; both needed to show fill. */
+	contextTokens?: number;
+	contextWindow?: number;
+	/** Context percentage, shown in parens after the fill; `null`/undefined omits it
+	 * (e.g. right after compaction, unknown until the next reply). */
+	contextPercent?: number | null;
+	/** All-in cost across every LLM call this session (main + subagents + one-shots). */
+	cost: number;
+	/** Latest turn's cache-hit rate; a per-turn health signal, not cumulative. */
+	cacheHitPercent?: number;
+	/** Open PR number for the current branch, when a `gh` lookup found one. */
+	pr?: number;
+	/** Short model name (already abbreviated by the caller). */
+	model?: string;
+	/** Effort label to show after the model — the level, or "✦ ultracode". */
+	effort?: string;
+}
+
+/** pi's token formatter, replicated so a "1.1M" here reads like pi's own. */
+export function formatTokens(count: number): string {
+	if (count < 1000) return count.toString();
+	if (count < 10000) return `${(count / 1000).toFixed(1)}k`;
+	if (count < 1000000) return `${Math.round(count / 1000)}k`;
+	if (count < 10000000) return `${(count / 1000000).toFixed(1)}M`;
+	return `${Math.round(count / 1000000)}M`;
+}
+
+/** Cost with cent-fraction precision for small spends, coarser once it grows. */
+export function formatCost(cost: number): string {
+	return `$${cost.toFixed(cost < 100 ? 3 : 2)}`;
+}
+
+/** Fold the home prefix to `~`. */
+function tilde(cwd: string, home: string): string {
+	if (home && (cwd === home || cwd.startsWith(`${home}/`))) return `~${cwd.slice(home.length)}`;
+	return cwd;
+}
+
+/**
+ * Fit a path into `max` columns, keeping the tail (the deepest, most specific
+ * folders) with a leading `…`. `max <= 1` collapses to just `…`.
+ */
+function truncatePath(path: string, max: number): string {
+	if (path.length <= max) return path;
+	if (max <= 1) return "…";
+	return `…${path.slice(path.length - (max - 1))}`;
+}
+
+interface Part {
+	plain: string;
+	painted: string;
+	/** Higher drops first when the line is too narrow; 0 = never dropped. */
+	dropPriority: number;
+}
+
+const SEP = " · ";
+
+/**
+ * Build the footer as a single line fit to `width`. When too narrow, the
+ * cache-hit rate drops first, then the PR (with the path/branch on the left),
+ * then the path itself; context, cost, model, and effort are the core and are
+ * kept (truncation is the last resort).
+ */
+export function buildFooterLines(data: FooterData, width: number, paint: Paint): string[] {
+	if (width <= 0) return [""];
+
+	const parts: Part[] = [];
+	// A labelled metric: the label is muted, the value takes `color`. The plain
+	// form (label + value) drives the width/drop math; the painted form colours
+	// the two halves separately.
+	const push = (label: string, value: string, color: string, dropPriority = 0) => {
+		if (!value) return;
+		const plain = label ? `${label} ${value}` : value;
+		const painted = label ? `${paint("muted", label)} ${paint(color, value)}` : paint(color, value);
+		parts.push({ plain, painted, dropPriority });
+	};
+
+	// Context fill as "usage: tokens/window (pct%)".
+	if (typeof data.contextTokens === "number" && typeof data.contextWindow === "number" && data.contextWindow > 0) {
+		const pct = typeof data.contextPercent === "number" ? ` (${data.contextPercent.toFixed(0)}%)` : "";
+		push("usage:", `${formatTokens(data.contextTokens)}/${formatTokens(data.contextWindow)}${pct}`, "dim");
+	}
+	// Total cost, always shown once known.
+	push("cost:", formatCost(data.cost), "dim");
+	// Cache-hit: a warning only when it drops low, otherwise dim; droppable.
+	if (typeof data.cacheHitPercent === "number") {
+		const color = data.cacheHitPercent < 20 ? "error" : data.cacheHitPercent < 50 ? "warning" : "dim";
+		push("cache-hit:", `${data.cacheHitPercent.toFixed(0)}%`, color, 2);
+	}
+	// Model, then effort — no labels; both self-describing.
+	if (data.model) push("", data.model, "dim");
+	if (data.effort) push("", data.effort, "accent");
+
+	// Left chunk: path + branch, with the open PR attached to the branch as
+	// "⎇ branch ← PR #123". The branch (short, useful) is kept and the path is
+	// head-truncated to fit; when the PR would not fit, it is dropped before the
+	// branch (bare-branch fallback), and only when there is no room even for the
+	// bare branch does the whole chunk go, leaving metrics alone. The three
+	// segments paint separately — path dim, branch in accent, PR in the link
+	// colour — but every width/gap decision uses their plain lengths.
+	const path = tilde(data.cwd, data.home);
+	const branchSeg = data.branch ? ` ⎇ ${data.branch}` : "";
+	const prSeg = data.branch && typeof data.pr === "number" ? ` ← PR #${data.pr}` : "";
+
+	// Drop optional right parts (highest priority first) until the metrics fit.
+	let kept = parts.slice();
+	const rightPlain = () => kept.map((p) => p.plain).join(SEP);
+	while (rightPlain().length > width) {
+		const droppable = kept
+			.map((p, i) => ({ p, i }))
+			.filter((x) => x.p.dropPriority > 0)
+			.sort((a, b) => b.p.dropPriority - a.p.dropPriority)[0];
+		if (!droppable) break;
+		kept = kept.filter((_, i) => i !== droppable.i);
+	}
+
+	const rightLen = rightPlain().length;
+
+	// Even the core overflows: last resort, truncate the plain metrics to width.
+	if (rightLen > width) {
+		return [paint("dim", rightPlain().slice(0, width))];
+	}
+
+	const rightPaintedStr = kept.map((p) => p.painted).join(paint("dim", SEP));
+
+	// Room for the left chunk after the metrics and at least one space of gap.
+	// Keep the PR only if the branch+PR both fit; otherwise drop it and keep the
+	// bare branch.
+	const room = width - rightLen - 1;
+	const keptPr = room >= branchSeg.length + prSeg.length + 1 ? prSeg : "";
+	const suffixLen = branchSeg.length + keptPr.length;
+	if (room >= suffixLen + 1) {
+		const shownPath = truncatePath(path, room - suffixLen);
+		const leftPlain = `${shownPath}${branchSeg}${keptPr}`;
+		const gap = " ".repeat(width - leftPlain.length - rightLen);
+		const leftPainted = `${paint("dim", shownPath)}${paint("accent", branchSeg)}${paint("mdLink", keptPr)}`;
+		return [`${leftPainted}${gap}${rightPaintedStr}`];
+	}
+	// No room for even the branch: metrics only, right-aligned.
+	const pad = " ".repeat(Math.max(0, width - rightLen));
+	return [`${pad}${rightPaintedStr}`];
+}
+
+/**
+ * All-in session cost and latest cache-hit rate, computed from the session
+ * entries: the main session exactly as pi's own footer does (assistant
+ * messages, tool-result and branch-summary/compaction usage) plus every
+ * persisted out-of-band usage entry (`recordUsage`). Reading the ledger from
+ * the entries, not process memory, is what keeps the figure honest across a
+ * `--continue`/`--session` restart. Kept pure and loosely typed so it tests
+ * with plain fixtures.
+ */
+export function computeMainUsage(entries: readonly unknown[]): { cost: number; cacheHitPercent?: number } {
+	let cost = 0;
+	let cacheHitPercent: number | undefined;
+	const num = (v: unknown) => (typeof v === "number" && Number.isFinite(v) ? v : 0);
+
+	for (const raw of entries) {
+		const entry = raw as {
+			type?: string;
+			message?: { role?: string; usage?: Record<string, unknown> };
+			usage?: Record<string, unknown>;
+		};
+		if (entry.type === "message" && entry.message?.role === "assistant" && entry.message.usage) {
+			const u = entry.message.usage;
+			cost += costOf(u);
+			// Only meaningful when the provider actually reported cache activity —
+			// otherwise leave it unset so the footer omits the field, matching pi
+			// (a non-caching provider must not show a permanent "cache-hit: 0%").
+			const cacheRead = num(u.cacheRead);
+			const hasCacheActivity = cacheRead > 0 || num(u.cacheWrite) > 0;
+			const prompt = num(u.input) + cacheRead + num(u.cacheWrite);
+			cacheHitPercent = hasCacheActivity && prompt > 0 ? (cacheRead / prompt) * 100 : undefined;
+		} else if (entry.type === "message" && entry.message?.role === "toolResult" && entry.message.usage) {
+			cost += costOf(entry.message.usage);
+		} else if ((entry.type === "branch_summary" || entry.type === "compaction") && entry.usage) {
+			cost += costOf(entry.usage);
+		} else {
+			// Out-of-band calls (subagents, classifier, readers, recap, setup)
+			// persisted by recordUsage — the all-in half of the total.
+			cost += usageEntryCost(entry);
+		}
+	}
+	return { cost, cacheHitPercent };
+}

package/extensions/footer/index.ts

@@ -0,0 +1,152 @@
+/**
+ * footer extension — replaces pi's built-in status line with One Code's own via
+ * `ctx.ui.setFooter`. A single line: path + branch on the left; context fill,
+ * all-in cost, cache-hit health, PR number, model, and effort on the right.
+ *
+ * pi's footer only ever sees the main session's usage. Here the cost figure is a
+ * true total: the main session (from its entries, exactly as pi computes it)
+ * plus every out-of-band LLM call (in-process subagents, the auto-mode
+ * classifier, and the reader-style one-shots — web-fetch, recap, and auto-mode
+ * setup — via the shared withReasoningFallback wrapper). Those are persisted as
+ * `one-code:usage` session entries by `recordUsage`, so the total survives a
+ * `--continue`/`--session` restart; the usage bus is only the live repaint
+ * signal. The effort label
+ * after the model reads the live thinking level, and swaps to "✦ ultracode" when
+ * the effort extension has published that status.
+ *
+ * Set CC_FOOTER=0 to keep pi's built-in footer instead.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { linesComponent, safeThemePaint } from "../lib/tui-render.ts";
+import { formatModel, isRealModel } from "../permissions/modes.ts";
+import { ULTRACODE_STATUS_KEY } from "../effort/slider.ts";
+import { USAGE_CHANNEL } from "../lib/usage-bus.ts";
+import { buildFooterLines, computeMainUsage, type FooterData } from "./footer-line.ts";
+import { fetchPrNumber } from "./pr.ts";
+
+export default function footerExtension(pi: ExtensionAPI) {
+	if (process.env.CC_FOOTER === "0") return;
+
+	// All-in cost + latest cache-hit, recomputed only when the session's entries
+	// change (message_end/agent_end, and a usage entry landing) — an O(n)
+	// transcript scan that must NOT run on every repaint (model/effort events
+	// change no entry).
+	let mainUsage: { cost: number; cacheHitPercent?: number } = { cost: 0 };
+	let lastCtx: ExtensionContext | undefined;
+	let pr: number | undefined;
+	/** Bumped per branch change so a slow gh lookup for an old branch is ignored. */
+	let prToken = 0;
+
+	/** Invalidate the memoized line and repaint; set once the footer mounts. */
+	let repaint = () => {};
+
+	const recomputeMain = (ctx: ExtensionContext) => {
+		lastCtx = ctx;
+		mainUsage = computeMainUsage(ctx.sessionManager.getEntries());
+	};
+
+	// A usage entry was just appended (recordUsage persists before it emits):
+	// re-sum the ledger. Known limitation: a background subagent spawned before
+	// a /clear (newSession) keeps reporting after the switch, so its late cost
+	// is persisted into — and shown for — the new session. Rare (only a
+	// *background* subagent outlives a turn — classifier/reader/recap/setup all
+	// finish synchronously), and it only nudges a display figure, so we accept
+	// it rather than thread session identity through the bus.
+	pi.events.on(USAGE_CHANNEL, () => {
+		if (lastCtx) recomputeMain(lastCtx);
+		repaint();
+	});
+
+	const refreshPr = (cwd: string, branch: string | null) => {
+		const token = ++prToken;
+		if (!branch) {
+			pr = undefined;
+			repaint();
+			return;
+		}
+		void fetchPrNumber(cwd, branch).then((found) => {
+			if (token !== prToken) return; // a newer branch superseded this lookup
+			pr = found;
+			repaint();
+		});
+	};
+
+	pi.on("session_start", (_event, ctx) => {
+		recomputeMain(ctx);
+		if (!ctx.hasUI) return;
+
+		ctx.ui.setFooter((tui: unknown, theme: unknown, footerData: unknown) => {
+			const paint = safeThemePaint(theme);
+			const fd = footerData as {
+				getGitBranch(): string | null;
+				getExtensionStatuses(): ReadonlyMap<string, string>;
+				/** Returns the unsubscribe (pi keeps callbacks in a Set for the process lifetime). */
+				onBranchChange(cb: () => void): () => void;
+			};
+
+			const snapshot = (): FooterData => {
+				const usage = ctx.getContextUsage();
+				const ultracode = fd.getExtensionStatuses().get(ULTRACODE_STATUS_KEY);
+				const effort = ultracode ?? safeThinkingLevel(ctx);
+				const model = ctx.model;
+				return {
+					cwd: ctx.cwd,
+					home: process.env.HOME || process.env.USERPROFILE || "",
+					branch: fd.getGitBranch() ?? undefined,
+					contextTokens: usage?.tokens ?? undefined,
+					contextWindow: usage?.contextWindow,
+					contextPercent: usage?.percent,
+					cost: mainUsage.cost,
+					cacheHitPercent: mainUsage.cacheHitPercent,
+					pr,
+					model: model && isRealModel(model.id) ? formatModel(model.provider, model.id) : "none",
+					effort,
+				};
+			};
+
+			const component = linesComponent((width) => buildFooterLines(snapshot(), width, paint));
+			repaint = () => {
+				component.invalidate();
+				(tui as { requestRender?: () => void } | undefined)?.requestRender?.();
+			};
+
+			// The branch drives the PR lookup; seed it now and follow changes. The
+			// factory re-runs on every session_start (/clear, /new, resume) and pi
+			// only disposes the component, so the subscription must be released
+			// here — otherwise each replaced footer keeps firing its `gh pr list`
+			// against a stale cwd on every branch change.
+			refreshPr(ctx.cwd, fd.getGitBranch());
+			const stopFollowingBranch = fd.onBranchChange(() => {
+				refreshPr(ctx.cwd, fd.getGitBranch());
+				repaint();
+			});
+
+			return Object.assign(component, {
+				dispose: () => {
+					stopFollowingBranch();
+					repaint = () => {};
+				},
+			});
+		});
+	});
+
+	// The main session's own entries changed: refresh the cached main-usage (the
+	// only place the O(n) transcript scan runs), then repaint.
+	pi.on("message_end", (_event, ctx) => {
+		recomputeMain(ctx);
+		repaint();
+	});
+	pi.on("agent_end", (_event, ctx) => {
+		recomputeMain(ctx);
+		repaint();
+	});
+	// Model/effort switches change only the label; no main-usage recompute needed.
+	pi.on("model_select", () => repaint());
+	pi.on("thinking_level_select", () => repaint());
+}
+
+/** Current effort/thinking level as a short label, or undefined if unavailable. */
+function safeThinkingLevel(ctx: ExtensionContext): string | undefined {
+	return ctx.thinkingLevel;
+}

package/extensions/footer/pr.ts

@@ -0,0 +1,53 @@
+/**
+ * Open-PR lookup for the footer, mirroring Claude Code's PR indicator. Uses the
+ * GitHub CLI (`gh`) so it inherits the user's existing auth; when `gh` is absent
+ * or the branch has no open PR it resolves to `undefined` and the footer simply
+ * omits the field — same graceful degrade as pi's git-branch watcher.
+ *
+ * `gh pr list --head <branch>`, not `gh pr view <branch>`: the latter only finds
+ * a PR whose head lives in the base repo, so it misses the common case of a PR
+ * opened from a fork (`isCrossRepository`), even though `list` on the base repo
+ * knows about it. `--state open` keeps a merged/closed PR for the same branch
+ * name from showing.
+ *
+ * The exec lives here but the parse is split out so it unit-tests without a
+ * subprocess.
+ */
+
+import { execFile } from "node:child_process";
+
+/**
+ * Pull the PR number out of `gh pr list --json number` output — a JSON array of
+ * PRs (possibly empty). The first open PR for the branch wins.
+ */
+export function parsePrNumber(stdout: string): number | undefined {
+	try {
+		const data = JSON.parse(stdout) as Array<{ number?: unknown }>;
+		if (!Array.isArray(data)) return undefined;
+		for (const pr of data) {
+			if (pr && typeof pr.number === "number" && Number.isFinite(pr.number)) return pr.number;
+		}
+		return undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+const LOOKUP_TIMEOUT_MS = 4000;
+
+/**
+ * Resolve the open PR number for `branch` in `cwd`, or `undefined`. Never
+ * rejects: any failure (no gh, no PR, detached HEAD, timeout) is `undefined`.
+ */
+export function fetchPrNumber(cwd: string, branch: string): Promise<number | undefined> {
+	return new Promise((resolve) => {
+		execFile(
+			"gh",
+			["pr", "list", "--head", branch, "--state", "open", "--json", "number"],
+			{ cwd, timeout: LOOKUP_TIMEOUT_MS, encoding: "utf8" },
+			(error, stdout) => {
+				resolve(error ? undefined : parsePrNumber(stdout));
+			},
+		);
+	});
+}

package/extensions/hooks/executor.ts

@@ -18,14 +18,41 @@
  * - output capped at 1MB per stream
  * - stdin errors ignored (a hook that exits without reading stdin — `exit 2`
  *   — would otherwise EPIPE-crash the write)
- * - timeout clamped under Node's 2^31-1 ms timer overflow, timer unref'd so a
- *   pending hook can't keep a one-shot `pi -p` process alive
+ * - stdin JSON is newline-terminated: without a trailing "\n" a hook doing
+ *   `read -r line` sees EOF-before-delimiter and `read` exits 1, so the
+ *   `if read -r line; then …` branch is silently skipped even though the
+ *   variable was populated (Claude Code carries the same fix — bug CC-161)
+ * - timeout clamped under Node's 2^31-1 ms timer overflow, timer unref'd (it
+ *   still fires while the process lives; it must not be what keeps it alive)
+ * - the child process handle stays REF'd while the hook runs, unless the caller
+ *   passes `detached` (SessionEnd at shutdown, fire-and-forget). Until
+ *   2026-09-05 every hook child was `unref()`d, and in a one-shot run
+ *   (`pi -p` / `--mode json`) a PreToolUse hook was often the only pending
+ *   work: the provider's keep-alive socket is idle between the response and
+ *   the tool's spawn, so nothing ref'd remained but the hook's stdio pipes.
+ *   When the child exited, the pipe-close callbacks could run before its
+ *   SIGCHLD-driven exit callback; with the process handle unref'd the loop
+ *   counted itself empty and node exited 0 mid-tool, silently, before the
+ *   hook's `close` ever fired — measured at ~55% of runs with a trivial
+ *   `exit 0` hook (docs/one-shot-lsp-event-loop-drain.md has the same
+ *   mechanism for the LSP client). A ref'd child holds the loop until `close`.
  */
 
 import { spawn } from "node:child_process";
+import { killProcessTree } from "../lib/process-tree.ts";
 
 export interface HookRunResult {
-	/** null when the process was killed (timeout) or never spawned. */
+	/**
+	 * null when the process was killed (timeout) or never spawned. Normalized on
+	 * the timeout path rather than taken from `waitpid`: a group SIGKILL is not
+	 * atomic, so the shell can be scheduled after its foreground child is killed
+	 * and before its own signal lands, reap the child and exit(128+9) itself —
+	 * `close` then reports a normal exit of 137 instead of death by signal
+	 * (roughly 1% of timeouts under load, and never when the shell had exec'd
+	 * away, leaving no shell to reap; findings §10.20). Callers should still
+	 * prefer `timedOut`, which says what happened rather than what it looked
+	 * like, but they no longer have to.
+	 */
 	exitCode: number | null;
 	timedOut: boolean;
 	/** Set when the child could not be spawned at all. */
@@ -41,6 +68,18 @@ export interface HookRunOptions {
 	timeoutSeconds?: number;
 	/** Exposed to the hook as CLAUDE_PROJECT_DIR; defaults to cwd. */
 	projectDir?: string;
+	/**
+	 * Let the process exit without waiting for this hook. Only for fire-and-forget
+	 * dispatches at shutdown; an awaited hook must keep the event loop alive or a
+	 * one-shot run drains mid-await (header). The child is `unref()`d AND spawned
+	 * without stdout/stderr pipes: `unref` releases the process handle only, and
+	 * each inherited pipe is a ref'd handle of its own that stays open until the
+	 * child exits — a `sleep 20` SessionEnd hook held a `-p` run open for the
+	 * full 20 s (LIFECYCLE-REVIEW-2026-09-06 M4, measured). stdin is still piped
+	 * for the payload, written and closed at once, and unref'd too. The result's
+	 * stdout/stderr are therefore empty for a detached hook — nothing reads them.
+	 */
+	detached?: boolean;
 }
 
 const MAX_OUTPUT_BYTES = 1_000_000;
@@ -58,7 +97,7 @@ export function runHookCommand(command: string, stdinJson: string, opts: HookRun
 			child = spawn("/bin/sh", ["-c", command], {
 				cwd: opts.cwd,
 				detached: true,
-				stdio: ["pipe", "pipe", "pipe"],
+				stdio: opts.detached ? ["pipe", "ignore", "ignore"] : ["pipe", "pipe", "pipe"],
 				env: { ...process.env, CLAUDE_PROJECT_DIR: opts.projectDir ?? opts.cwd },
 			});
 		} catch (error) {
@@ -72,7 +111,12 @@ export function runHookCommand(command: string, stdinJson: string, opts: HookRun
 			});
 			return;
 		}
-		child.unref();
+		if (opts.detached) {
+			child.unref();
+			// The stdin pipe is the one handle left; it closes as soon as the
+			// payload is flushed below, and must not hold the loop meanwhile.
+			(child.stdin as { unref?: () => void } | null)?.unref?.();
+		}
 
 		let stdout = "";
 		let stderr = "";
@@ -91,21 +135,10 @@ export function runHookCommand(command: string, stdinJson: string, opts: HookRun
 		child.stdout?.on("data", capture("stdout"));
 		child.stderr?.on("data", capture("stderr"));
 
-		const killTree = () => {
-			// Negative pid = the whole process group the detached shell leads.
-			try {
-				if (child.pid) process.kill(-child.pid, "SIGKILL");
-			} catch {
-				try {
-					child.kill("SIGKILL");
-				} catch {
-					// Already gone.
-				}
-			}
-		};
 		const timer = setTimeout(() => {
 			timedOut = true;
-			killTree();
+			// The whole process group the detached shell leads (lib/process-tree.ts).
+			killProcessTree(child, "SIGKILL");
 		}, timeoutMs);
 		timer.unref();
 
@@ -120,13 +153,17 @@ export function runHookCommand(command: string, stdinJson: string, opts: HookRun
 			finish({ exitCode: null, timedOut, spawnError: error.message, stdout, stderr });
 		});
 		child.on("close", (code) => {
-			finish({ exitCode: code, timedOut, stdout, stderr });
+			// A killed process reports null here, EXCEPT when the shell outlived the
+			// group kill just long enough to reap its child and exit 128+9 itself
+			// (see exitCode's contract). Normalizing keeps "we killed it" from ever
+			// looking like an ordinary non-zero exit, which fails OPEN downstream.
+			finish({ exitCode: timedOut ? null : code, timedOut, stdout, stderr });
 		});
 
 		// A hook that never reads stdin (e.g. plain `exit 2`) closes the pipe
 		// early; the resulting EPIPE must not take the extension down.
 		child.stdin?.on("error", () => {});
-		child.stdin?.write(stdinJson);
+		child.stdin?.write(stdinJson.endsWith("\n") ? stdinJson : `${stdinJson}\n`);
 		child.stdin?.end();
 	});
 }

package/extensions/hooks/formatter-notice.ts

@@ -0,0 +1,76 @@
+/**
+ * Telling the model when a PostToolUse hook rewrote the file it just edited.
+ *
+ * A "formatter" hook is the common shape of PostToolUse, and its rewrite was
+ * invisible: this extension loads before `file-tracker` and AWAITS the hook, so
+ * by the time the tracker observes the file the hook's version is already on
+ * disk and gets recorded as the model's own write. With sequential edits the
+ * model was told nothing at all (3/3 runs, zero reminders); with parallel edits
+ * it was told by a race, about the wrong file. A tiny-tier model then showed
+ * the user its pre-hook text from memory (WEAK-MODEL-REVIEW-2026-09-06 M1).
+ *
+ * Claude Code has a dedicated notice for exactly this, delivered as hook
+ * context on the edit's own result. This module is the deterministic detector
+ * behind ours: snapshot the target before the hooks run, compare after.
+ */
+
+import { readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { isWritingTool, pathArgument } from "../auto-mode/paths.ts";
+
+/**
+ * Reading the whole file twice per edit is fine for source files and wrong for
+ * a large generated one; past this size the comparison falls back to the disk
+ * stamp, which a rewrite moves anyway.
+ */
+const MAX_COMPARE_BYTES = 2 * 1024 * 1024;
+
+/**
+ * What a file looked like at snapshot time: its content, or its stamp when too
+ * large. `undefined` is "nothing comparable" — missing, binary or unreadable —
+ * which every caller already treats as "make no claim".
+ */
+export type FileSnapshot = { kind: "content"; value: string } | { kind: "stamp"; value: string };
+
+/**
+ * The absolute path a file tool is acting on, or undefined for any other tool.
+ * The tool set and the `path`/`file_path` field names come from `auto-mode/paths.ts`,
+ * the one place that knows them, so a new writing tool is added once.
+ */
+export function fileToolTarget(toolName: string, input: unknown, cwd: string): string | undefined {
+	if (!isWritingTool(toolName)) return undefined;
+	const raw = pathArgument(input as Record<string, unknown> | undefined);
+	if (!raw?.trim()) return undefined;
+	return resolve(cwd, raw);
+}
+
+export function snapshotFile(path: string): FileSnapshot | undefined {
+	try {
+		const stat = statSync(path);
+		if (stat.size > MAX_COMPARE_BYTES) return { kind: "stamp", value: `${stat.mtimeMs}:${stat.size}` };
+		return { kind: "content", value: readFileSync(path, "utf-8") };
+	} catch {
+		// Missing, binary, or unreadable: nothing we could compare meaningfully.
+		return undefined;
+	}
+}
+
+/** True when the file differs from the snapshot. An unreadable file compares equal (nothing to claim). */
+export function changedSince(path: string, before: FileSnapshot | undefined): boolean {
+	if (!before) return false;
+	const after = snapshotFile(path);
+	if (!after) return false;
+	// A kind change means the file crossed the MAX_COMPARE_BYTES boundary between
+	// snapshots — the size changed, so the file changed. (Comparing values across
+	// kinds is meaningless: a stamp is never equal to file content.)
+	if (after.kind !== before.kind) return true;
+	return after.value !== before.value;
+}
+
+/**
+ * Claude Code's wording, with our tool names: the model must know the bytes on
+ * disk are no longer the bytes it wrote, without being sent into a revert (the
+ * hook's change is intentional).
+ */
+export const FORMATTER_NOTICE = (path: string) =>
+	`PostToolUse hook modified ${path} after your edit (likely a formatter). The change was intentional — do not revert it. Your next edit will not fail with a stale-file error, but if its old text targets a region the hook reformatted, read the file first, and read it before reporting the file's contents to the user.`;