one-code-extension 0.1.0

package/extensions/effort/slider.ts

@@ -0,0 +1,253 @@
+/**
+ * The `/effort` slider (pure): choices, key decoding, and layout.
+ *
+ * Claude Code presents reasoning effort as a Faster→Smarter track with
+ * `ultracode` sitting past the top, separated by a divider because it is not
+ * simply "more thinking" — it is the top reasoning level plus standing workflow
+ * orchestration.
+ *
+ * The plain stops are pi's own thinking ladder, deliberately *all* of it: pi
+ * reserves shift+tab for `app.thinking.cycle` and refuses to let an extension
+ * rebind it, so that key keeps cycling the full ladder no matter what we do.
+ * A slider offering a different set would mean two dials disagreeing about the
+ * same number, so this one covers the same stops and adds ultracode. Everything
+ * user-facing calls it "effort"; "thinking level" is pi's internal name for it.
+ *
+ * Rendering and key handling live here so the layout is unit-testable without a
+ * terminal; `index.ts` only wires it to pi.
+ */
+
+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";
+
+/** The reasoning level ultracode pins, when the model can reach it. */
+export const ULTRACODE_LEVEL: ThinkingLevel = "xhigh";
+
+/** pi's thinking ladder, Faster→Smarter — the same stops shift+tab cycles. */
+export const THINKING_LEVELS: readonly ThinkingLevel[] = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+
+/** Track stops: pi's ladder, then ultracode past the divider. */
+export const EFFORT_CHOICES = [...THINKING_LEVELS, ULTRACODE] as const;
+export type EffortChoice = (typeof EFFORT_CHOICES)[number];
+
+export function isEffortChoice(value: string): value is EffortChoice {
+	return (EFFORT_CHOICES as readonly string[]).includes(value);
+}
+
+/** Parse a typed argument (`/effort xhigh`). Returns undefined if unrecognised. */
+export function parseEffortArg(arg: string): EffortChoice | undefined {
+	const value = arg.trim().toLowerCase();
+	return value && isEffortChoice(value) ? value : undefined;
+}
+
+export function acceptedEffortArgs(): string[] {
+	return [...EFFORT_CHOICES];
+}
+
+/** The thinking level a choice maps to; ultracode pins the top plus a mode. */
+export function thinkingLevelFor(choice: EffortChoice): ThinkingLevel {
+	return choice === ULTRACODE ? ULTRACODE_LEVEL : (choice as ThinkingLevel);
+}
+
+/** Which choice a current thinking level should preselect on the track. */
+export function choiceForState(level: ThinkingLevel | undefined, ultracodeActive: boolean): EffortChoice {
+	if (ultracodeActive) return ULTRACODE;
+	if (level && isEffortChoice(level)) return level;
+	return "medium";
+}
+
+export type SliderKey = "left" | "right" | "first" | "last" | "confirm" | "cancel";
+
+/**
+ * Decode a raw terminal chunk. `Component.handleInput` hands over bytes, not key
+ * names, so the sequences are matched directly: CSI C/D for arrows (plus the
+ * older SS3 form some terminals still send), CR/LF to confirm, ESC to cancel.
+ */
+export function decodeKey(data: string): SliderKey | undefined {
+	switch (data) {
+		case "\x1b[C":
+		case "\x1bOC":
+		case "l":
+			return "right";
+		case "\x1b[D":
+		case "\x1bOD":
+		case "h":
+			return "left";
+		case "\x1b[H":
+		case "\x1b[1~":
+			return "first";
+		case "\x1b[F":
+		case "\x1b[4~":
+			return "last";
+		case "\r":
+		case "\n":
+			return "confirm";
+		case "\x1b":
+		case "\x03": // ctrl+c — same intent as escape while a picker is focused
+			return "cancel";
+		default:
+			return undefined;
+	}
+}
+
+/**
+ * Step the marker to the next *enabled* stop in a direction, skipping levels the
+ * current model can't reach so the marker can only ever land on a selectable
+ * stop. `first`/`last` jump to the first/last enabled stop.
+ */
+export function moveIndex(index: number, key: SliderKey, enabled: boolean[]): number {
+	switch (key) {
+		case "left":
+			for (let i = index - 1; i >= 0; i--) if (enabled[i]) return i;
+			return index;
+		case "right":
+			for (let i = index + 1; i < enabled.length; i++) if (enabled[i]) return i;
+			return index;
+		case "first": {
+			const first = enabled.indexOf(true);
+			return first >= 0 ? first : index;
+		}
+		case "last": {
+			const last = enabled.lastIndexOf(true);
+			return last >= 0 ? last : index;
+		}
+		default:
+			return index;
+	}
+}
+
+/**
+ * Which track stops the active model can reach, aligned to `EFFORT_CHOICES`. A
+ * plain level is enabled when the model lists it as supported; `ultracode` is
+ * enabled whenever the model can reason at all (its pinned level clamps to the
+ * model's ceiling). Unsupported stops stay on the track — dimmed and skipped by
+ * navigation — rather than being hidden: shift+tab (pi's own dial, which we
+ * can't rebind) still cycles the supported plain levels, so a slider that
+ * dropped stops would just disagree with it. We show the whole ladder and grey
+ * out what this model can't do.
+ */
+export function enabledStops(supported: readonly ThinkingLevel[]): boolean[] {
+	const set = new Set(supported);
+	const canReason = supported.some((level) => level !== "off");
+	return EFFORT_CHOICES.map((choice) => (choice === ULTRACODE ? canReason : set.has(choice as ThinkingLevel)));
+}
+
+/** Snap an index onto the nearest enabled stop, preferring the higher side on a tie. */
+export function nearestEnabled(index: number, enabled: boolean[]): number {
+	if (enabled[index]) return index;
+	for (let d = 1; d < enabled.length; d++) {
+		if (index + d < enabled.length && enabled[index + d]) return index + d;
+		if (index - d >= 0 && enabled[index - d]) return index - d;
+	}
+	const first = enabled.indexOf(true);
+	return first >= 0 ? first : index;
+}
+
+/** Rank of a plain level on the ladder (off=0 … max), or -1 if not a plain level. */
+export function levelRank(level: ThinkingLevel): number {
+	return THINKING_LEVELS.indexOf(level);
+}
+
+export type Paint = (color: string, text: string) => string;
+
+export interface SliderView {
+	index: number;
+	/** Which stops the active model can reach, aligned to `EFFORT_CHOICES`. */
+	enabled: boolean[];
+	/** Terminal width, so a narrow pane degrades instead of wrapping. */
+	width: number;
+	/** Model name for the "unsupported" note; omitted falls back to "this model". */
+	modelLabel?: string;
+}
+
+const TITLE = "Effort";
+const HINTS = "←/→ adjust · Enter confirm · Esc cancel · shift+tab cycles the plain levels";
+const SHORT_HINTS = "←/→ · Enter · Esc";
+const ULTRACODE_SUBTITLE = `${ULTRACODE_LEVEL} + workflows`;
+
+/**
+ * One label cell per stop, padded so the marker row lines up under the label
+ * it belongs to. The divider before `ultracode` is what tells the user it is a
+ * different kind of thing rather than one more notch of thinking.
+ */
+function cells(): { label: string; divider: boolean }[] {
+	return EFFORT_CHOICES.map((choice) => ({ label: choice, divider: choice === ULTRACODE }));
+}
+
+export function renderEffortSlider(view: SliderView, paint: Paint): string[] {
+	const stops = cells();
+	const gap = 2;
+	const divider = " │ ";
+
+	// Lay the label row out first, recording where each label starts, so the
+	// track and marker rows can be built against real column positions.
+	let labels = "";
+	const positions: number[] = [];
+	for (const [i, stop] of stops.entries()) {
+		if (i > 0) labels += stop.divider ? divider : " ".repeat(gap);
+		positions.push([...labels].length);
+		labels += stop.label;
+	}
+	const plainWidth = [...labels].length;
+
+	const selected = stops[view.index];
+	const markerColumn = positions[view.index] + Math.floor([...selected.label].length / 2);
+
+	const trackRow = Array.from({ length: plainWidth }, () => "─");
+	// Keep the divider visible on the track itself, not just under the labels.
+	const dividerIndex = stops.findIndex((s) => s.divider);
+	if (dividerIndex > 0) {
+		const at = positions[dividerIndex] - 2;
+		if (at >= 0 && at < trackRow.length) trackRow[at] = "│";
+	}
+
+	const styledLabels = stops
+		.map((stop, i) => {
+			// Disabled stops are dimmed even when unselected, so an unsupported level
+			// reads as greyed-out rather than merely inactive.
+			const color = i === view.index ? "accent" : view.enabled[i] ? "muted" : "dim";
+			return { text: paint(color, stop.label), divider: stop.divider };
+		})
+		.reduce((acc, cur, i) => acc + (i > 0 ? (cur.divider ? paint("dim", divider) : " ".repeat(gap)) : "") + cur.text, "");
+
+	const endsRow = `${paint("dim", "Faster")}${" ".repeat(Math.max(1, plainWidth - "Faster".length - "Smarter".length))}${paint("dim", "Smarter")}`;
+	const markerRow = `${" ".repeat(markerColumn)}${paint("accent", "▲")}`;
+	const subtitleRow =
+		selected.label === ULTRACODE
+			? `${" ".repeat(Math.max(0, positions[stops.length - 1]))}${paint("dim", ULTRACODE_SUBTITLE)}`
+			: "";
+
+	// Rows are (plain content, styled content) pairs: nothing wraps for us, and a
+	// wrapped line would shift the marker out from under its label, so widths are
+	// measured on the unstyled text — escape codes would inflate the count.
+	const rows: [plain: string, styled: string][] = [
+		[TITLE, paint("accent", TITLE)],
+		["", ""],
+		[`Faster${" ".repeat(Math.max(1, plainWidth - 13))}Smarter`, endsRow],
+		[trackRow.join(""), paint("muted", trackRow.join(""))],
+		[`${" ".repeat(markerColumn)}▲`, markerRow],
+		[labels, styledLabels],
+	];
+	if (subtitleRow) rows.push([`${" ".repeat(Math.max(0, positions[stops.length - 1]))}${ULTRACODE_SUBTITLE}`, subtitleRow]);
+	// When the model can't reach every stop, say so — the dimming alone doesn't
+	// explain itself, and it points at shift+tab for the ones we grey out.
+	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(["", ""], [HINTS, paint("dim", HINTS)]);
+
+	const fits = rows.every(([plainRow]) => [...plainRow].length <= view.width);
+	if (fits) return rows.map(([, styled]) => styled);
+
+	// Too narrow for the track (or for the hint line): drop to one stop list and
+	// the shortest usable hint, both clipped, rather than let anything wrap.
+	const clip = (text: string) => [...text].slice(0, view.width).join("");
+	const list = stops.map((s) => s.label);
+	return [
+		paint("accent", clip(TITLE)),
+		clip(list.join(" · ")).replace(list[view.index], (m) => paint("accent", m)),
+		paint("dim", clip(SHORT_HINTS)),
+	];
+}

package/extensions/exit/index.ts

@@ -0,0 +1,28 @@
+/**
+ * exit extension — Claude Code's `/exit`.
+ *
+ * pi's built-in quit command is `/quit`; Claude Code's is `/exit` (with `quit`
+ * shown as an alias). A user coming from Claude Code types `/exit` out of habit
+ * and, without this, it isn't a command — so it goes to the model as a message
+ * instead of quitting. This registers `/exit` alongside pi's `/quit`, routed
+ * through the same graceful path (`ctx.shutdown()` — "Gracefully shutdown pi and
+ * exit", the same call `/quit` makes).
+ *
+ * We cannot reproduce Claude Code's single `/exit (quit)` palette entry that is
+ * findable by either word: pi has no command aliases and its command palette
+ * fuzzy-matches the command NAME only (`autocomplete.ts` — the description is
+ * displayed but never searched). So `/exit` and the built-in `/quit` are two
+ * separate entries, each found by its own name; both quit. That's the behaviour
+ * a Claude Code user needs, without patching pi.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export default function exitExtension(pi: ExtensionAPI) {
+	pi.registerCommand("exit", {
+		description: "Quit One Code (same as /quit)",
+		handler: async (_args, ctx) => {
+			ctx.shutdown();
+		},
+	});
+}

package/extensions/file-tracker/index.ts

@@ -0,0 +1,103 @@
+/**
+ * file-tracker extension — Claude Code's read-before-write discipline.
+ *
+ * - `edit`/`write`/`notebook_edit` on a file that exists but was never read is
+ *   blocked with an instruction to read it first.
+ * - An edit to a file that changed since we last saw it is blocked, so the model
+ *   cannot overwrite someone else's change.
+ * - Files that change out of band are reported in a `<system-reminder>` with the
+ *   new content around the change, line-numbered.
+ *
+ * Tracking is by content, not by tool call, which is what makes it catch writes
+ * that went through bash and never touched an intercepted tool.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { REMINDER_CHANNEL } from "../lib/reminders.ts";
+import { describeChanges, EXTERNAL_CHANGE_REMINDER, 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"]);
+
+function readIfPresent(path: string): string | undefined {
+	if (!existsSync(path)) return undefined;
+	try {
+		return readFileSync(path, "utf-8");
+	} catch {
+		// Binary or unreadable: not something we can reason about, so don't guard it.
+		return undefined;
+	}
+}
+
+function pathOf(input: unknown, cwd: string): string | undefined {
+	const raw = (input as { path?: unknown })?.path;
+	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();
+
+	pi.on("tool_call", (event, ctx) => {
+		if (!GUARDED_TOOLS.has(event.toolName)) return undefined;
+		const path = pathOf(event.input, ctx.cwd);
+		if (!path) return undefined;
+
+		const current = readIfPresent(path);
+		const status = tracker.status(path, current);
+
+		// Creating a new file needs no prior read.
+		if (status === "absent" || status === "fresh") return undefined;
+		if (status === "unread") return { block: true, reason: UNREAD_REASON(path, event.toolName) };
+		return { block: true, reason: STALE_REASON(path) };
+	});
+
+	pi.on("tool_result", (event, ctx) => {
+		if (event.isError) return undefined;
+		if (!READ_TOOLS.has(event.toolName) && !GUARDED_TOOLS.has(event.toolName)) return undefined;
+
+		const path = pathOf(event.input, ctx.cwd);
+		if (!path) return undefined;
+
+		// 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());
+		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.
+	 */
+	pi.on("before_agent_start", () => {
+		for (const path of tracker.tracked) {
+			const previous = tracker.lastSeen(path);
+			if (previous === undefined || previous === "") continue;
+			const current = readIfPresent(path);
+			if (current === undefined) {
+				tracker.forget(path);
+				pi.events.emit(REMINDER_CHANNEL, {
+					text: `${path} no longer exists; it was deleted or moved after you read it.`,
+				});
+				continue;
+			}
+			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) });
+			}
+			// …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);
+		}
+	});
+}

package/extensions/file-tracker/tracker.ts

@@ -0,0 +1,145 @@
+/**
+ * File freshness tracking (pure).
+ *
+ * Claude Code refuses to edit a file the model hasn't read, refuses to write over
+ * one it hasn't seen, rejects an edit when the file changed after the read, and
+ * reports out-of-band changes with a line-numbered excerpt. Together these stop
+ * the model from clobbering someone else's edit — including its own edits made
+ * through bash, which no tool hook can see.
+ *
+ * This module holds the state machine; `index.ts` wires it to pi's events.
+ */
+
+export type FreshnessStatus = "fresh" | "unread" | "stale" | "absent";
+
+export interface TrackedFile {
+	/** Content as of the last read or write we performed. */
+	content: string;
+	at: number;
+}
+
+/** Keeps memory bounded on long sessions with large files. */
+const MAX_TRACKED_FILES = 300;
+const MAX_TRACKED_BYTES = 512 * 1024;
+
+export class FileTracker {
+	private files = new Map<string, TrackedFile>();
+	/**
+	 * 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
+	 * read: Claude Code reports the change *and* still requires a fresh read
+	 * before editing. Storing it here suppresses repeat warnings without
+	 * clearing the stale state.
+	 */
+	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 {
+		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 });
+		} else {
+			this.files.set(path, { content, at });
+		}
+		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]);
+		}
+	}
+
+	forget(path: string): void {
+		this.files.delete(path);
+		this.notified.delete(path);
+	}
+
+	/** True when this exact content has already been reported for this path. */
+	alreadyNotified(path: string, content: string): boolean {
+		return this.notified.get(path) === content;
+	}
+
+	markNotified(path: string, content: string): void {
+		this.notified.set(path, content);
+	}
+
+	has(path: string): boolean {
+		return this.files.has(path);
+	}
+
+	lastSeen(path: string): string | undefined {
+		return this.files.get(path)?.content;
+	}
+
+	get tracked(): string[] {
+		return [...this.files.keys()];
+	}
+
+	/**
+	 * `absent`  — the file does not exist (a write creates it, which is fine)
+	 * `unread`  — it exists but we have never looked at it
+	 * `stale`   — it changed since we last saw it
+	 * `fresh`   — what we last saw matches what is on disk
+	 */
+	status(path: string, currentContent: string | undefined): FreshnessStatus {
+		if (currentContent === undefined) return "absent";
+		const known = this.files.get(path);
+		if (!known) return "unread";
+		// Oversized files are tracked without content; treat them as fresh rather
+		// than blocking edits we cannot reason about.
+		if (known.content === "" && currentContent !== "") return "fresh";
+		return known.content === currentContent ? "fresh" : "stale";
+	}
+}
+
+export interface ChangeExcerpt {
+	firstChangedLine: number;
+	text: string;
+}
+
+/**
+ * Renders the changed region of a file the way Claude Code does: the *new* lines,
+ * numbered, with a little context. Deliberately not a full diff — the model needs
+ * to know what the file says now, not the history of how it got there.
+ */
+export function describeChanges(
+	previous: string,
+	current: string,
+	options: { context?: number; maxLines?: number } = {},
+): ChangeExcerpt | undefined {
+	if (previous === current) return undefined;
+
+	const contextLines = options.context ?? 2;
+	const maxLines = options.maxLines ?? 40;
+	const before = previous.split("\n");
+	const after = current.split("\n");
+
+	let prefix = 0;
+	while (prefix < before.length && prefix < after.length && before[prefix] === after[prefix]) prefix++;
+
+	let suffix = 0;
+	while (
+		suffix < before.length - prefix &&
+		suffix < after.length - prefix &&
+		before[before.length - 1 - suffix] === after[after.length - 1 - suffix]
+	) {
+		suffix++;
+	}
+
+	const start = Math.max(0, prefix - contextLines);
+	const end = Math.min(after.length, after.length - suffix + contextLines);
+	const shown = after.slice(start, end).slice(0, maxLines);
+
+	const numbered = shown.map((line, index) => `${start + index + 1}\t${line}`).join("\n");
+	const truncated = end - start > maxLines ? `\n… ${end - start - maxLines} more changed lines` : "";
+
+	return { firstChangedLine: prefix + 1, text: `${numbered}${truncated}` };
+}
+
+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.`;
+
+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.`;
+
+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}`;

package/extensions/hooks/debug.ts

@@ -0,0 +1,53 @@
+/**
+ * Hook observability, mirroring auto-mode's: CC_HOOKS_DEBUG=1 for live
+ * per-invocation lines, and an opt-in JSONL (`hooks-decisions.jsonl` next to
+ * the approval store) for after-the-fact "what fired and what did it decide".
+ * Logging must never break a hook's fail-open guarantee, so append failures
+ * are swallowed (same stance as auto-mode/decision-log.ts).
+ */
+
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { oneCodeStateDir } from "../lib/paths.ts";
+
+export interface HookLogEntry {
+	ts: string;
+	sessionId?: string;
+	event: string;
+	scope: string;
+	command: string;
+	decision: "allow" | "block" | "context" | "error";
+	reason?: string;
+	exitCode: number | null;
+	durationMs: number;
+}
+
+export function hooksDebugEnabled(): boolean {
+	const value = process.env.CC_HOOKS_DEBUG;
+	return value === "1" || value === "2";
+}
+
+const COMMAND_LIMIT = 120;
+
+export function clipCommand(command: string): string {
+	const flat = command.replace(/\s+/g, " ").trim();
+	return flat.length > COMMAND_LIMIT ? `${flat.slice(0, COMMAND_LIMIT)}…` : flat;
+}
+
+export function formatDebugLine(entry: Omit<HookLogEntry, "ts" | "sessionId">): string {
+	const reason = entry.reason ? ` — ${entry.reason}` : "";
+	return `[hooks] ${entry.event} (${entry.scope}) ${clipCommand(entry.command)} → ${entry.decision}${reason} (${entry.durationMs}ms)`;
+}
+
+export function hooksLogPath(): string {
+	return join(oneCodeStateDir(), "hooks", "hooks-decisions.jsonl");
+}
+
+export function appendHookLog(entry: HookLogEntry, file = hooksLogPath()): void {
+	try {
+		mkdirSync(dirname(file), { recursive: true });
+		appendFileSync(file, `${JSON.stringify(entry)}\n`);
+	} catch {
+		// Never break a hook over its diary.
+	}
+}