one-code-extension 0.4.1 → 0.6.0

package/extensions/tool-style/index.ts

@@ -6,20 +6,28 @@
  * same mechanism the bash extension uses). Every model-facing field —
  * description, promptSnippet, promptGuidelines, parameters — is passed through
  * from pi's own definition byte-identical, so the system prompt and tool
- * schemas are unchanged; execution delegates to a per-cwd instance of pi's
+ * schemas are unchanged, with one exception: write carries Claude Code's
+ * description, short or long by the model's tier (write-description.ts,
+ * lib/tool-variants.ts), and is registered again when the form changes.
+ * Execution delegates to a per-cwd instance of pi's
  * real definition (they close over cwd, and enter_worktree moves the session
  * mid-run). Only the TUI renderers differ: a `●` call line, and the base
  * result component indented under a `⎿` elbow so upstream streaming,
  * truncation, and ctrl+o expansion behavior is preserved. Edit keeps its own
  * call component (the diff preview a permission prompt relies on) with just
- * the header line restyled.
+ * the header line restyled. Write renders as Claude Code's Write
+ * (write-render.ts): a preview of the content or the diff while it waits, then
+ * "Wrote N lines" or "Added N lines, removed M lines"; to show an overwrite's
+ * diff afterwards, its execution reads the old file first and records the diff
+ * on the result's details, which never reach the model.
  *
  * grep/find/ls stay tier-gated: registering them does not bypass the
  * search-tools extension, which reconciles the active-tool list on
  * session_start/model_select and removes them for frontier models.
  */
 
-import type { ExtensionAPI, ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { readFile, stat } from "node:fs/promises";
+import type { ExtensionAPI, ExtensionToolContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import {
 	createEditToolDefinition,
 	createFindToolDefinition,
@@ -27,9 +35,14 @@ import {
 	createLsToolDefinition,
 	createReadToolDefinition,
 	createWriteToolDefinition,
+	generateDiffString,
 } from "@earendil-works/pi-coding-agent";
 import { perCwd } from "../lib/per-cwd.ts";
-import { ccWrapBuiltinRenderers } from "../lib/tui-render.ts";
+import { type DescriptionForm, registerFormTool } from "../lib/tool-variants.ts";
+import { resolveToolPath } from "../lib/tool-path.ts";
+import { ccWrapBuiltinRenderers, type RejectedFileOp } from "../lib/tui-render.ts";
+import { editDescription, writeDescription } from "./write-description.ts";
+import { createWriteRenderers, WRITE_DIFF_MAX_BYTES, type WriteRenderDeps, writeDetails } from "./write-render.ts";
 
 // The concrete definitions are each strongly typed to their own schema; this
 // extension treats them uniformly, so the spec is deliberately loose. Every
@@ -41,6 +54,12 @@ interface BuiltinSpec {
 	create: (cwd: string) => BuiltinDefinition;
 	title: (args: Record<string, unknown> | undefined) => string | undefined;
 	keepBaseCall?: boolean;
+	/** A file tool: a rejection without a reason reads "User rejected <op> to <path>". */
+	rejectedAs?: RejectedFileOp;
+	/** Write's own Claude Code renderers and result details. */
+	write?: boolean;
+	/** A description in place of pi's, by the session's description form; `base` is pi's own. */
+	description?: (form: DescriptionForm, base: string) => string;
 }
 
 const asSpecCreate = (create: (cwd: string) => unknown): BuiltinSpec["create"] =>
@@ -48,24 +67,51 @@ const asSpecCreate = (create: (cwd: string) => unknown): BuiltinSpec["create"] =
 
 const BUILTINS: BuiltinSpec[] = [
 	{ label: "Read", create: asSpecCreate(createReadToolDefinition), title: (a) => a?.path as string | undefined },
-	{ label: "Write", create: asSpecCreate(createWriteToolDefinition), title: (a) => a?.path as string | undefined },
+	{
+		label: "Write",
+		create: asSpecCreate(createWriteToolDefinition),
+		title: (a) => a?.path as string | undefined,
+		rejectedAs: "write",
+		write: true,
+		description: writeDescription,
+	},
 	{
 		label: "Update",
 		create: asSpecCreate(createEditToolDefinition),
 		title: (a) => a?.path as string | undefined,
 		keepBaseCall: true,
+		rejectedAs: "update",
+		description: (_form, base) => editDescription(base),
 	},
 	{ label: "Grep", create: asSpecCreate(createGrepToolDefinition), title: (a) => a?.pattern as string | undefined },
 	{ label: "Find", create: asSpecCreate(createFindToolDefinition), title: (a) => a?.pattern as string | undefined },
 	{ label: "LS", create: asSpecCreate(createLsToolDefinition), title: (a) => (a?.path as string | undefined) ?? "." },
 ];
 
+/**
+ * The file a write is about to replace, for its diff: undefined when there is
+ * none, null when it is not a readable file or too big to diff.
+ */
+const readBefore: WriteRenderDeps["readBefore"] = async (raw, cwd) => {
+	const path = resolveToolPath(raw, cwd);
+	try {
+		const info = await stat(path);
+		if (!info.isFile() || info.size > WRITE_DIFF_MAX_BYTES) return null;
+		return await readFile(path, "utf8");
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code === "ENOENT" ? undefined : null;
+	}
+};
+
+const writeDeps: WriteRenderDeps = { readBefore, diff: (before, after) => generateDiffString(before, after).diff };
+
 export default function toolStyleExtension(pi: ExtensionAPI) {
 	for (const spec of BUILTINS) {
 		const base = spec.create(process.cwd());
 		const forCwd = perCwd(spec.create);
+		const renderers = ccWrapBuiltinRenderers(spec.label, base, { title: spec.title, keepBaseCall: spec.keepBaseCall, rejectedAs: spec.rejectedAs });
 
-		pi.registerTool({
+		const definition = {
 			name: base.name,
 			label: base.label,
 			description: base.description,
@@ -75,10 +121,22 @@ export default function toolStyleExtension(pi: ExtensionAPI) {
 			executionMode: base.executionMode,
 			prepareArguments: base.prepareArguments,
 			constrainedSampling: base.constrainedSampling,
-			...ccWrapBuiltinRenderers(spec.label, base, { title: spec.title, keepBaseCall: spec.keepBaseCall }),
-			async execute(toolCallId, params, signal, onUpdate, ctx: ExtensionContext) {
-				return forCwd(ctx.cwd).execute(toolCallId, params as never, signal, onUpdate, ctx);
+			...(spec.write ? createWriteRenderers(writeDeps, renderers.renderResult) : renderers),
+			async execute(toolCallId, params, signal, onUpdate, ctx: ExtensionToolContext) {
+				const run = () => forCwd(ctx.cwd).execute(toolCallId, params as never, signal, onUpdate, ctx);
+				if (!spec.write) return run();
+				const { path, content } = params as { path?: unknown; content?: unknown };
+				if (typeof path !== "string" || typeof content !== "string") return run();
+				const before = await readBefore(path, ctx.cwd);
+				const result = await run();
+				return { ...result, details: writeDetails(before, content, writeDeps.diff) };
 			},
-		} as ToolDefinition);
+		} as ToolDefinition;
+		const describe = spec.description;
+		if (!describe) {
+			pi.registerTool(definition);
+			continue;
+		}
+		registerFormTool(pi, definition, (form) => describe(form, base.description));
 	}
 }

package/extensions/tool-style/write-description.ts

@@ -0,0 +1,40 @@
+/**
+ * The write tool's model-facing description: Claude Code's Write text (pure).
+ *
+ * pi's own write tool runs underneath (tool-style/index.ts); only the
+ * description is Claude Code's, short on frontier and workhorse, long on cheap
+ * and tiny (lib/tool-variants.ts), with One Code's tool names. "Overwriting an
+ * existing file you haven't read will fail" holds here: the file tracker
+ * refuses it (file-tracker/tracker.ts). Read and edit keep pi's descriptions,
+ * because Claude Code's describe a different call shape (`file_path`,
+ * numbered lines, `old_string`); edit's gets the read rule appended
+ * (`editDescription`).
+ */
+
+import type { DescriptionForm } from "../lib/tool-variants.ts";
+
+export const WRITE_SHORT_DESCRIPTION = `Writes a file to the local filesystem, overwriting if one exists.
+
+When to use: creating a new file, or fully replacing one you've already read. Overwriting an existing file you haven't read will fail. For partial changes, use edit instead.`;
+
+export const WRITE_LONG_DESCRIPTION = `Writes a file to the local filesystem.
+
+Usage:
+- This tool will overwrite the existing file if there is one at the provided path.
+- If this is an existing file, you MUST use the read tool first to read the file's contents. This tool will fail if you did not read the file first.
+- Prefer the edit tool for modifying existing files — it only sends the diff. Only use this tool to create new files or for complete rewrites.
+- NEVER create documentation files (*.md) or README files unless explicitly requested by the User.
+- Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.`;
+
+export function writeDescription(form: DescriptionForm): string {
+	return form === "long" ? WRITE_LONG_DESCRIPTION : WRITE_SHORT_DESCRIPTION;
+}
+
+/**
+ * pi's edit description plus the rule the file tracker enforces, which pi's
+ * text does not state (write's does). Without it, GPT-6 models read with `cat`
+ * and met the refusal first (2026-10-04 Codex self-test: 16 refused edits).
+ */
+export function editDescription(base: string): string {
+	return `${base} The file must have been read in this conversation, with the read tool or a shell command that printed the whole file as it is on disk (such as cat), or the edit is refused; if it changed on disk since, read it again first.`;
+}

package/extensions/tool-style/write-render.ts

@@ -0,0 +1,237 @@
+/**
+ * The write tool's transcript, as Claude Code shows a Write (pure: no pi
+ * imports; tool-style/index.ts wires it over pi's write tool).
+ *
+ * - While the call waits to run (a permission prompt sits under it), the call
+ *   line carries a preview of what it will write: the new file's first lines,
+ *   or the diff against the file it overwrites. The prompt's decision depends
+ *   on it, the way edit's diff preview serves an edit prompt.
+ * - Once it ran: `⎿ Wrote N lines to <path>` and the file's first lines for a
+ *   new file, `⎿ Added N lines, removed M lines` and the diff for an
+ *   overwrite.
+ * - Rejected without a reason: `⎿ User rejected write to <path>` and the
+ *   first lines it would have written.
+ *
+ * The content preview stops after WRITE_PREVIEW_LINES lines with a
+ * `… +N lines (ctrl+o to expand)` trailer (ctrl+o works inside the prompt
+ * too); a diff shows whole, as edit's does. Every line is wrapped to the
+ * width, never cut, so nothing in an overwide line hides past the edge.
+ */
+
+import { hardWrapColumns } from "../lib/text-width.ts";
+import { sanitizeDisplayText } from "../lib/terminal-text.ts";
+import {
+	callLine,
+	countNoun,
+	displayToolPath,
+	EXPAND_HINT,
+	elbowIndent,
+	linesComponent,
+	rejectedFileHead,
+	spinnerBulletColor,
+	stripReminderBlocks,
+	summarizeArgs,
+	textContent,
+	type ThemeLike,
+	type TuiComponent,
+} from "../lib/tui-render.ts";
+import { userDenialKind } from "../lib/user-denial.ts";
+
+/** Content lines shown before the `… +N lines` trailer (Claude Code's). */
+export const WRITE_PREVIEW_LINES = 10;
+
+/** An overwrite's diff is computed only when both sides are at most this big; past it the result reads as a create. */
+export const WRITE_DIFF_MAX_BYTES = 512 * 1024;
+
+/**
+ * What a finished write did, on its result's `details` (display-only: tool
+ * result details never reach the model). `diff` is pi's display diff
+ * (`+12 line`, `-12 line`, ` 12 line`), absent when it was too big to compute.
+ */
+export type WriteDetails = { kind: "create" } | { kind: "update"; diff?: string };
+
+/** Lines in the content, a trailing newline ending the last line rather than starting another (Claude Code's count). */
+export function countLines(content: string): number {
+	const parts = content.split("\n");
+	return content.endsWith("\n") ? parts.length - 1 : parts.length;
+}
+
+/** The details a finished write carries: `before` is the file's old content, undefined when it did not exist, null when it was not read. */
+export function writeDetails(before: string | null | undefined, content: string, diff: (before: string, after: string) => string): WriteDetails {
+	if (before === undefined) return { kind: "create" };
+	if (before === null || before.length > WRITE_DIFF_MAX_BYTES || content.length > WRITE_DIFF_MAX_BYTES) return { kind: "update" };
+	return { kind: "update", diff: diff(before, content) };
+}
+
+/** One source line made safe and wrapped: escapes and control characters removed, tabs as spaces. */
+function wrapLine(line: string, width: number): string[] {
+	const safe = sanitizeDisplayText(line.replace(/\t/g, "   "));
+	return safe === "" ? [""] : hardWrapColumns(safe, Math.max(1, width));
+}
+
+/** The content's first lines (all when expanded), wrapped to `width`, with the `… +N lines` trailer. */
+export function contentPreviewLines(theme: ThemeLike, content: string, width: number, expanded: boolean): string[] {
+	const total = countLines(content);
+	const source = (content || "(No content)").split("\n");
+	if (content.endsWith("\n")) source.pop();
+	const shown = expanded ? source : source.slice(0, WRITE_PREVIEW_LINES);
+	const out = shown.flatMap((line) => wrapLine(line, width).map((part) => theme.fg("toolOutput", part)));
+	const hidden = total - shown.length;
+	if (!expanded && hidden > 0) out.push(theme.fg("dim", `… +${countNoun(hidden, "line")} (${EXPAND_HINT})`));
+	return out;
+}
+
+const DIFF_COLOR: Record<string, string> = { "+": "toolDiffAdded", "-": "toolDiffRemoved" };
+
+/** pi's display diff, each line coloured by its sign and wrapped to `width`. */
+export function diffPreviewLines(theme: ThemeLike, diff: string, width: number): string[] {
+	if (diff === "") return [];
+	return diff.split("\n").flatMap((line) => {
+		const color = DIFF_COLOR[line[0]] ?? "toolDiffContext";
+		return wrapLine(line, width).map((part) => theme.fg(color, part));
+	});
+}
+
+/** Added and removed lines in pi's display diff. */
+export function diffCounts(diff: string): { added: number; removed: number } {
+	let added = 0;
+	let removed = 0;
+	for (const line of diff.split("\n")) {
+		if (line.startsWith("+")) added++;
+		else if (line.startsWith("-")) removed++;
+	}
+	return { added, removed };
+}
+
+/** Claude Code's "Added N lines, removed M lines" (either half alone when the other is zero). */
+export function updateSummary(theme: ThemeLike, diff: string): string {
+	const { added, removed } = diffCounts(diff);
+	const plural = (n: number) => (n > 1 ? "lines" : "line");
+	const parts: string[] = [];
+	if (added > 0) parts.push(`Added ${theme.bold(String(added))} ${plural(added)}`);
+	if (removed > 0) parts.push(`${added > 0 ? "r" : "R"}emoved ${theme.bold(String(removed))} ${plural(removed)}`);
+	return parts.length > 0 ? parts.join(", ") : "No changes";
+}
+
+/** The waiting call's preview body, wrapped to `width`: the diff for an overwrite it could diff, the new content otherwise. */
+export function writePreviewLines(theme: ThemeLike, preview: WriteDetails, content: string, width: number, expanded: boolean): string[] {
+	return preview.kind === "update" && preview.diff !== undefined
+		? diffPreviewLines(theme, preview.diff, width)
+		: contentPreviewLines(theme, content, width, expanded);
+}
+
+/**
+ * A finished write's result body, before the `⎿` elbow is added: the summary
+ * line, then the content preview or the diff, wrapped to `width`. `path` is
+ * the display path.
+ */
+export function writeResultLines(theme: ThemeLike, details: WriteDetails | undefined, path: string, content: string, width: number, expanded: boolean): string[] {
+	if (details?.kind === "update" && details.diff !== undefined) {
+		return [updateSummary(theme, details.diff), ...diffPreviewLines(theme, details.diff, width)];
+	}
+	const head = `Wrote ${theme.bold(String(countLines(content)))} lines to ${theme.bold(sanitizeDisplayText(path))}`;
+	return [head, ...contentPreviewLines(theme, content, width, expanded)];
+}
+
+/** A write rejected without a reason: "User rejected write to <path>" and the first lines it would have written. */
+export function rejectedWriteLines(theme: ThemeLike, path: string, content: string, width: number, expanded: boolean): string[] {
+	return [rejectedFileHead(theme, "write", path), ...contentPreviewLines(theme, content, width, expanded)];
+}
+
+/** The I/O the renderers need, injected so this module stays pure. */
+export interface WriteRenderDeps {
+	/** The file's content: undefined when it does not exist, null when it cannot or should not be read (too big, a directory). */
+	readBefore: (path: string, cwd: string) => Promise<string | null | undefined>;
+	/** pi's display diff of two contents. */
+	diff: (before: string, after: string) => string;
+}
+
+interface WriteArgs {
+	path?: unknown;
+	file_path?: unknown;
+	content?: unknown;
+}
+
+/** The waiting call's preview, kept on the row's `context.state` across renders. */
+interface PreviewState {
+	path: string;
+	content: string;
+	preview?: WriteDetails;
+	lines?: { width: number; expanded: boolean; lines: string[] };
+}
+
+const argPath = (args: WriteArgs | undefined): string | undefined => {
+	const raw = args?.path ?? args?.file_path;
+	return typeof raw === "string" && raw !== "" ? raw : undefined;
+};
+
+type ResultRenderer = (result: any, options: { expanded: boolean; isPartial: boolean }, theme: any, context: any) => TuiComponent;
+
+/**
+ * renderCall/renderResult for the write tool. `fallbackResult` renders what
+ * this view does not own (an error, a rejection with a reason): the generic
+ * wrapper around pi's own result component.
+ */
+export function createWriteRenderers(
+	deps: WriteRenderDeps,
+	fallbackResult: ResultRenderer,
+): {
+	renderShell: "self";
+	renderCall: (args: WriteArgs, theme: any, context: any) => TuiComponent;
+	renderResult: ResultRenderer;
+} {
+	/** The preview for these args, starting the read of the target the first time. */
+	const previewFor = (path: string, content: string, context: any): PreviewState => {
+		const state = context.state as { ccWritePreview?: PreviewState };
+		const current = state.ccWritePreview;
+		if (current && current.path === path && current.content === content) return current;
+		const next: PreviewState = { path, content };
+		state.ccWritePreview = next;
+		const cwd = typeof context.cwd === "string" ? context.cwd : process.cwd();
+		const settle = (preview: WriteDetails) => {
+			if (state.ccWritePreview !== next) return;
+			next.preview = preview;
+			context.invalidate?.();
+		};
+		deps.readBefore(path, cwd).then(
+			(before) => settle(writeDetails(before, content, deps.diff)),
+			() => settle({ kind: "create" }),
+		);
+		return next;
+	};
+
+	return {
+		renderShell: "self",
+		renderCall(args, theme: ThemeLike, context) {
+			const path = argPath(args);
+			const header = callLine(theme, "Write", path ? summarizeArgs(path) : "", context.isPartial, context.isError, spinnerBulletColor(context));
+			const content = args?.content;
+			// The preview belongs to the call that has not run yet: once its result
+			// is in, the result carries the content (or the diff) instead.
+			const waiting = context.isPartial && context.argsComplete && path !== undefined && typeof content === "string";
+			const preview = waiting ? previewFor(path, content, context) : undefined;
+			const expanded = context.expanded === true;
+			return linesComponent((width) => {
+				if (!preview?.preview) return [header];
+				const cached = preview.lines;
+				if (cached && cached.width === width && cached.expanded === expanded) return [header, ...cached.lines];
+				const body = writePreviewLines(theme, preview.preview, preview.content, width - 2, expanded).map((line) => `  ${line}`);
+				preview.lines = { width, expanded, lines: body };
+				return [header, ...body];
+			});
+		},
+		renderResult(result, options, theme: ThemeLike, context) {
+			const args = context.args as WriteArgs | undefined;
+			const path = argPath(args);
+			const content = args?.content;
+			if (path === undefined || typeof content !== "string") return fallbackResult(result, options, theme, context);
+			const shownPath = displayToolPath(path, context.cwd);
+			if (context.isError) {
+				if (userDenialKind(textContent(stripReminderBlocks(result))) !== "stop") return fallbackResult(result, options, theme, context);
+				return linesComponent((width) => elbowIndent(rejectedWriteLines(theme, shownPath, content, width - 5, options.expanded)));
+			}
+			const details = result?.details as WriteDetails | undefined;
+			return linesComponent((width) => elbowIndent(writeResultLines(theme, details, shownPath, content, width - 5, options.expanded)));
+		},
+	};
+}

package/extensions/turn-duration/index.ts

@@ -8,13 +8,15 @@
  * the model never sees its own timing line), rendered dim and led by the ✻ mark
  * to match CC's TurnDurationMessage. CC shows it after every response with no
  * threshold and defaults it on; CC_TURN_DURATION=0 opts out. The completion verb
- * is sampled once per turn from CC's 8-verb list.
+ * is sampled once per turn from CC's 8-verb list. The line ends with CC's
+ * `· done <time>` (the entry's timestamp, line.ts formatDoneAt) and, when
+ * background shells outlive the turn, `· N shells still running`.
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { trackShellTasks } from "../lib/shell-tasks.ts";
 import { dimMarkedLine } from "../lib/tui-render.ts";
-import { TURN_MARK, turnDurationText } from "./line.ts";
+import { formatDoneAt, TURN_MARK, turnDurationText } from "./line.ts";
 import { TurnSpan } from "./span.ts";
 import { pickCompletionVerb } from "./verbs.ts";
 
@@ -33,7 +35,9 @@ export default function turnDurationExtension(pi: ExtensionAPI) {
 	pi.registerEntryRenderer<TurnDurationData>(ENTRY_TYPE, (entry, _options, theme) => {
 		const data = entry.data;
 		if (!data) return undefined;
-		return dimMarkedLine(theme, TURN_MARK, turnDurationText(data.verb, data.durationMs, data.runningShells ?? 0));
+		// The entry's own timestamp is when the turn settled: Claude Code's `· done 2:33 PM`.
+		const doneAt = formatDoneAt(new Date(entry.timestamp));
+		return dimMarkedLine(theme, TURN_MARK, turnDurationText(data.verb, data.durationMs, data.runningShells ?? 0, doneAt));
 	});
 
 	const span = new TurnSpan();

package/extensions/turn-duration/line.ts

@@ -13,10 +13,53 @@ export const TURN_MARK = "✻";
 
 /**
  * `<Verb> for <duration>` — duration formatted like the spinner's elapsed
- * clock — plus Claude Code's background-shell tail (`· 2 shells still
- * running`) when shells outlive the turn.
+ * clock — then Claude Code's ` · done <time>` when the finish time is known,
+ * then its background-shell tail (`· 2 shells still running`) when shells
+ * outlive the turn.
  */
-export function turnDurationText(verb: string, durationMs: number, runningShells = 0): string {
+export function turnDurationText(verb: string, durationMs: number, runningShells = 0, doneAt?: string): string {
+	const done = doneAt ? ` · done ${doneAt}` : "";
 	const shells = runningShells > 0 ? ` · ${countNoun(runningShells, "shell")} still running` : "";
-	return `${verb} for ${formatDuration(0, durationMs)}${shells}`;
+	return `${verb} for ${formatDuration(0, durationMs)}${done}${shells}`;
+}
+
+/**
+ * The locale Claude Code formats times in: `LC_ALL`, then `LC_TIME`, then
+ * `LANG`, with the encoding and modifier dropped (`en_US.UTF-8` → `en-US`);
+ * undefined for `C`, `POSIX`, unset or a tag Intl rejects, which leaves the
+ * runtime's default.
+ */
+export function timeLocale(env: NodeJS.ProcessEnv = process.env): string | undefined {
+	const raw = env.LC_ALL || env.LC_TIME || env.LANG || "";
+	if (!raw || raw === "C" || raw === "POSIX") return undefined;
+	const tag = raw.split(".")[0]?.split("@")[0]?.replaceAll("_", "-");
+	if (!tag) return undefined;
+	try {
+		new Intl.DateTimeFormat(tag);
+		return tag;
+	} catch {
+		return undefined;
+	}
+}
+
+const DAY_MS = 86_400_000;
+
+/** Midnight of `date`'s calendar day, in the runtime's local time zone. */
+function localDay(date: Date): number {
+	return new Date(date.getFullYear(), date.getMonth(), date.getDate()).getTime();
+}
+
+/**
+ * Claude Code's "done" time (its `auto` time format): the time alone for a
+ * turn that finished today (`2:33 PM`), the weekday too within the last week
+ * (`Friday 2:33 PM`), and the date as well before that (`Friday, Sep 19, 2:33
+ * PM`), in the locale's own hour cycle. Empty for an invalid date.
+ */
+export function formatDoneAt(at: Date, now: Date = new Date(), locale: string | undefined = timeLocale()): string {
+	if (Number.isNaN(at.getTime())) return "";
+	const days = Math.round((localDay(now) - localDay(at)) / DAY_MS);
+	const time: Intl.DateTimeFormatOptions = { hour: "numeric", minute: "2-digit" };
+	const options: Intl.DateTimeFormatOptions =
+		days === 0 ? time : days > 0 && days < 7 ? { weekday: "long", ...time } : { weekday: "long", month: "short", day: "numeric", ...time };
+	return new Intl.DateTimeFormat(locale, options).format(at);
 }

package/extensions/web/backends.ts

@@ -73,12 +73,12 @@ const KEYLESS_ADVICE =
  * these results are best-effort and what the user can configure instead.
  */
 export const KEYLESS_NOTE =
-	"Note: these results came from Exa's free keyless endpoint (rate-limited, best-effort) because no search API key is configured. " +
+	"Note: these results came from Exa's free keyless endpoint (rate-limited, best-effort). " +
 	`For reliable search the user can ${KEYLESS_ADVICE}`;
 
 /** User-facing one-time notice (TUI) the first time a session searches keyless. */
 export const KEYLESS_USER_NOTICE =
-	"web_search used Exa's free keyless endpoint (rate-limited, best-effort): this provider has no native web search and no search API key is configured. " +
+	"web_search used Exa's free keyless endpoint (rate-limited, best-effort). " +
 	`For reliable results ${KEYLESS_ADVICE}`;
 
 // ---------------------------------------------------------------------------
@@ -140,19 +140,16 @@ export function resolveChain(
 
 function hostOf(url: string): string | undefined {
 	try {
-		return new URL(url).hostname.toLowerCase();
+		return new URL(url).hostname.toLowerCase().replace(/\.+$/, "");
 	} catch {
 		return undefined;
 	}
 }
 
 function normalizeDomain(domain: string): string {
-	return domain
-		.trim()
-		.toLowerCase()
-		.replace(/^https?:\/\//, "")
-		.replace(/^www\./, "")
-		.replace(/\/.*$/, "");
+	const value = domain.trim().toLowerCase();
+	const host = hostOf(/^https?:\/\//.test(value) ? value : `https://${value}`);
+	return (host ?? value).replace(/^www\./, "");
 }
 
 function hostMatches(host: string, domain: string): boolean {

package/extensions/web/description.ts

@@ -0,0 +1,50 @@
+/**
+ * web_search's model-facing description (pure).
+ *
+ * The short form, on frontier and workhorse models, is One Code's own: it
+ * names the backends that answer and how the domain filters apply to each.
+ * The long form, on cheap and tiny models (lib/tool-variants.ts), is the text
+ * Claude Code writes for its weakest models, addressed to the model rather
+ * than to Claude, with the backends line in place of "Web search is only
+ * available in the US".
+ */
+
+import type { DescriptionForm } from "../lib/tool-variants.ts";
+
+export const WEB_SEARCH_SHORT_DESCRIPTION =
+	"Search the web. Returns result blocks with titles and URLs.\n\n" +
+	"- `allowed_domains` / `blocked_domains` filter results (enforced on Brave/Tavily/Exa; with provider-native search they become `site:` operators in the query, best-effort).\n" +
+	'- After answering from results, end with a "Sources:" list of the URLs you used as markdown links.\n' +
+	"- Uses the model provider's own search when it has one; otherwise a configured search API (Brave, Tavily) or, with no key, a free rate-limited endpoint — the result names which.";
+
+export const WEB_SEARCH_LONG_DESCRIPTION = `
+- Allows you to search the web and use the results to inform responses
+- Provides up-to-date information for current events and recent data
+- Returns search result information formatted as search result blocks, including links as markdown hyperlinks
+- Use this tool for accessing information beyond your knowledge cutoff
+- Searches are performed automatically within a single API call
+
+CRITICAL REQUIREMENT - You MUST follow this:
+  - After answering the user's question, you MUST include a "Sources:" section at the end of your response
+  - In the Sources section, list all relevant URLs from the search results as markdown hyperlinks: [Title](URL)
+  - This is MANDATORY - never skip including sources in your response
+  - Example format:
+
+    [Your answer here]
+
+    Sources:
+    - [Source Title 1](https://example.com/1)
+    - [Source Title 2](https://example.com/2)
+
+Usage notes:
+  - Domain filtering is supported to include or block specific websites
+  - Uses the model provider's own search when it has one; otherwise a configured search API (Brave, Tavily) or, with no key, a free rate-limited endpoint — the result names which
+
+IMPORTANT - Use the correct year in search queries:
+  - The current month is (provided in the conversation below). You MUST use this year when searching for recent information, documentation, or current events.
+  - Example: If the user asks for "latest React docs", search for "React documentation" with the current year, NOT last year
+`;
+
+export function webSearchDescription(form: DescriptionForm): string {
+	return form === "long" ? WEB_SEARCH_LONG_DESCRIPTION : WEB_SEARCH_SHORT_DESCRIPTION;
+}