Make OSC 8 file:// terminal hyperlinks clickable (#1617)

* Make OSC 8 file:// terminal hyperlinks clickable

ghostty underlines OSC 8 cells on hover at the renderer level, but the
app's link provider dropped every non-http(s) URI, so file:// links from
agents (Claude Code wraps printed paths via pathToFileURL when
FORCE_HYPERLINK=1 — which dev3 itself sets) had hover affordance and a
dead click. Accept file URIs with an empty/localhost host, convert them
back to a local path (Windows drive form included, trailing :line:col
carried out), and activate through the existing resolveTerminalPaths +
activateTerminalPath flow so the allowed-roots policy and the file-open
setting keep applying.

* Open the OSC 8 link under the cursor, not the cached one

ghostty-web keys its link cache by hyperlink id and gives every OSC 8 link
on screen the same id, answering a hit-test from that cache before it scans
the clicked row. Every link therefore activated whichever one was scanned
first, so the hover tooltip named one file and the click opened another.

Activation now re-resolves the cell under the pointer through shared cell
math, and moves into activateOsc8Uri so the branch is testable: a file URI
that cannot become a path no longer falls through to window.open, and
percent-decoding can no longer re-introduce control characters into the
path. The link suffix parser is bounded and the refusal message names both
reasons a path can fail.

---------

Co-authored-by: h0x91B <h0x91b@gmail.com>

Author: arditti

change-logs/2026/09/01/fix-osc8-file-links-clickable.md

@@ -0,0 +1,5 @@
+Short: Terminal file links open the right file
+
+Terminal file paths that agents wrap in OSC 8 file:// hyperlinks (Claude Code does) showed a hover underline but a dead click: the link provider accepted only http(s) URIs. file:// links now Cmd/Ctrl+Click open like plain path links — resolved on the backend against the allowed roots, then previewed or revealed per the "File path click action" setting. Clicking an OSC 8 link also opens the link actually under the cursor: every such link on screen shares one hyperlink id, so the terminal's own link cache used to answer every click with whichever link was hovered first, and the hover tooltip named one file while the click opened another.
+
+Suggested by @arditti (h0x91b/dev-3.0#1617)

decisions/2026/09/01/osc8-click-reresolves-the-hovered-cell.md

@@ -0,0 +1,52 @@
+# OSC 8 activation re-resolves the cell under the cursor
+
+## Context
+
+Making OSC 8 `file://` hyperlinks clickable turned a wrong-link click from "opens
+the wrong URL in a browser" into "opens the wrong file off the disk", and it made
+the hover tooltip load-bearing: OSC 8 lets the visible label differ from the
+target, so the tooltip is the only thing on screen that names where a click will
+go. That only holds if the click and the tooltip agree.
+
+## Investigation
+
+They did not. In the running app, with four `file://` links on screen, hovering
+the first one and then clicking the fourth opened the first one's file — and
+reversing the hover order reversed the outcome. Reproduced identically with three
+`https` links, so it predates the file-URI work.
+
+The mechanism is in `ghostty-web`'s `LinkDetector` (`dist/ghostty-web.js`,
+`cacheLink` / `getLinkAt`): it caches a link under the key `h<hyperlinkId>` when
+the range's first cell carries a hyperlink id, and it answers a hit-test from
+that cache **before** it scans the clicked row. ghostty assigns the same
+hyperlink id to every OSC 8 link on screen — including when the emitter sends
+distinct `id=` parameters — so one cache entry serves every link, and the first
+row scanned after a write owns all of them until the next write clears the cache.
+dev3's own provider is not involved: it resolves each row correctly, which is
+exactly why the tooltip and the click disagreed.
+
+## Decision
+
+`ILink.activate` no longer trusts the URI its closure captured. It asks
+`cellFromEvent` for the cell under the pointer and re-resolves the link there
+(`createOsc8LinkProvider` in `src/mainview/terminal-osc8-links.ts`), falling back
+to its own URI when the pointer is off the grid. The cell math is shared with the
+hover tooltip through `cellFromMouseEvent` (`src/mainview/terminal-cell-hit.ts`)
+so the two surfaces cannot drift apart again. Activation itself moved into
+`activateOsc8Uri` (`src/mainview/terminal-path-open.ts`) so the branch is
+testable without a terminal.
+
+## Risks
+
+The fallback keeps the stale URI when `cellFromEvent` returns nothing, so a click
+whose coordinates do not land on the grid still behaves as before. The
+re-resolution costs one row scan per click, which is what a hover already does on
+every frame. If a future ghostty-web assigns real per-link ids, this becomes
+redundant but stays correct.
+
+## Alternatives considered
+
+Patching the upstream cache key was rejected as it means carrying a fork of
+`ghostty-web` for a defect we can neutralise in three lines on our side. Not
+registering the provider's ranges at all (handling clicks on the canvas
+ourselves) would duplicate ghostty's hit-testing and lose its hover underline.

src/mainview/TerminalView.tsx

@@ -48,9 +48,10 @@ import { createAnsiThemeFilter } from "./utils/ansi-theme-adapt";
 import { submitPastedText } from "./terminal-submit";
 import { createFilePathLinkProvider, type FilePathLinkProvider } from "./terminal-file-links";
 import { createOsc8Tracker, createOsc8LinkProvider } from "./terminal-osc8-links";
+import { cellFromMouseEvent } from "./terminal-cell-hit";
 import { installOsc8HoverTooltip, type Osc8HoverHandle } from "./terminal-osc8-hover";
 import { installFilePathUnderlines, type FilePathUnderlinesHandle } from "./terminal-link-underlines";
-import { activateTerminalPath } from "./terminal-path-open";
+import { activateTerminalPath, activateOsc8Uri } from "./terminal-path-open";
 import { isRemote } from "./utils/platform";
 import { paneHighlightRect, type PaneRectPct } from "./utils/paneHighlight";
 import TerminalSearchBar, { type TerminalSearchBarHandle } from "./components/TerminalSearchBar";
@@ -808,8 +809,9 @@ function TerminalView({ ptyUrl, taskId, projectId, onReady, onNativeStatus, onSe
 					return term.buffer.active.getLine(y)?.isWrapped;
 				},
 				uriFor: osc8Tracker.uriFor,
+				cellFromEvent: (event) => cellFromMouseEvent(term, event),
 				onActivate: (uri) => {
-					window.open(uri, "_blank", "noopener,noreferrer");
+					void activateOsc8Uri(uri, { t: tRef.current, taskId, projectId });
 				},
 			});
 			term.registerLinkProvider(osc8Provider);

src/mainview/__tests__/terminal-cell-hit.test.ts

@@ -0,0 +1,43 @@
+import { describe, it, expect } from "vitest";
+import { cellFromMouseEvent } from "../terminal-cell-hit";
+import type { Terminal } from "ghostty-web";
+
+function fakeTerm(opts: { bufferLength?: number; viewportY?: number } = {}): Terminal {
+	const canvas = document.createElement("canvas");
+	canvas.getBoundingClientRect = () => ({ left: 100, top: 50 }) as DOMRect;
+	return {
+		renderer: { charWidth: 10, charHeight: 20, getCanvas: () => canvas },
+		buffer: { active: { length: opts.bufferLength ?? 24 } },
+		rows: 24,
+		cols: 80,
+		viewportY: opts.viewportY ?? 0,
+	} as unknown as Terminal;
+}
+
+function at(term: Terminal, clientX: number, clientY: number) {
+	return cellFromMouseEvent(term, new MouseEvent("click", { clientX, clientY }));
+}
+
+describe("cellFromMouseEvent", () => {
+	it("maps a point to the cell under it, relative to the canvas", () => {
+		expect(at(fakeTerm(), 100, 50)).toEqual({ x: 0, y: 0, viewportRow: 0 });
+		expect(at(fakeTerm(), 135, 91)).toEqual({ x: 3, y: 2, viewportRow: 2 });
+	});
+
+	it("offsets by the scrollback so the row is an absolute buffer row", () => {
+		// 100 rows in the buffer, 24 on screen, scrolled to the bottom.
+		expect(at(fakeTerm({ bufferLength: 100 }), 100, 50)?.y).toBe(76);
+	});
+
+	it("returns nothing outside the grid", () => {
+		expect(at(fakeTerm(), 99, 50)).toBeUndefined();
+		expect(at(fakeTerm(), 100, 49)).toBeUndefined();
+		expect(at(fakeTerm(), 100 + 80 * 10, 50)).toBeUndefined();
+		expect(at(fakeTerm(), 100, 50 + 24 * 20)).toBeUndefined();
+	});
+
+	it("returns nothing before the renderer has measured a cell", () => {
+		const term = { renderer: { charWidth: 0, charHeight: 0, getCanvas: () => null } } as unknown as Terminal;
+		expect(at(term, 10, 10)).toBeUndefined();
+	});
+});

src/mainview/__tests__/terminal-osc8-links.test.ts

@@ -3,6 +3,8 @@ import {
 	createOsc8Tracker,
 	createOsc8LinkProvider,
 	safeHttpUri,
+	safeFileUri,
+	fileUriToLocalPath,
 	type HyperlinkLine,
 } from "../terminal-osc8-links";
 import type { ILink } from "ghostty-web";
@@ -161,6 +163,40 @@ describe("createOsc8LinkProvider", () => {
 		expect(onActivate).toHaveBeenCalledWith("https://x.dev", expect.anything());
 	});
 
+	it("activates the link under the cursor, not the ILink it was handed", () => {
+		// ghostty-web keys its link cache by hyperlink id and gives every OSC 8
+		// link on screen the same id, so a click in row 1 arrives carrying the
+		// ILink built for row 0. The cell under the cursor has to win, or the
+		// hover tooltip promises one target and the click opens another.
+		const rows: Record<number, HyperlinkLine> = {
+			0: lineOf("ONE", [1, 1, 1]),
+			1: lineOf("TWO", [1, 1, 1]),
+		};
+		const uriFor = (label: string) =>
+			label === "ONE" ? "file:///tmp/one.txt" : label === "TWO" ? "file:///tmp/two.txt" : undefined;
+		const onActivate = vi.fn();
+		const provider = createOsc8LinkProvider({
+			getLine: (row) => rows[row],
+			isRowWrapped: () => false,
+			uriFor,
+			cellFromEvent: () => ({ y: 1, x: 0 }),
+			onActivate,
+		});
+		let links: ILink[] = [];
+		provider.provideLinks(0, (found) => {
+			links = found ?? [];
+		});
+		expect(links[0].text).toBe("file:///tmp/one.txt");
+		links[0].activate(new MouseEvent("click", { metaKey: true }));
+		expect(onActivate).toHaveBeenCalledWith("file:///tmp/two.txt", expect.anything());
+	});
+
+	it("keeps its own URI when the click lands on no link at all", () => {
+		const { links, onActivate } = collectLinks({ 0: lineOf("#7", [1, 1]) }, () => "https://x.dev", 0);
+		links[0].activate(new MouseEvent("click", { metaKey: true }));
+		expect(onActivate).toHaveBeenCalledWith("https://x.dev", expect.anything());
+	});
+
 	it("falls back to the label itself when it is a safe URI", () => {
 		const text = "https://self.dev";
 		const { links } = collectLinks({ 0: lineOf(text, text.split("").map(() => 2)) }, () => undefined, 0);
@@ -169,16 +205,28 @@ describe("createOsc8LinkProvider", () => {
 	});
 
 	it("drops unknown labels and unsafe URIs", () => {
-		const text = "#9 file";
+		const text = "#9 evil";
 		const ids = [1, 1, 0, 3, 3, 3, 3];
 		const { links } = collectLinks(
 			{ 0: lineOf(text, ids) },
-			(l) => (l === "file" ? "file:///etc/passwd" : undefined),
+			(l) => (l === "evil" ? "javascript:alert(1)" : undefined),
 			0,
 		);
 		expect(links).toHaveLength(0);
 	});
 
+	it("produces a link for a file:// URI (agents wrap printed paths in them)", () => {
+		const text = "read a.png ok";
+		const ids = [0, 0, 0, 0, 0, 2, 2, 2, 2, 2, 0, 0, 0];
+		const { links } = collectLinks(
+			{ 0: lineOf(text, ids) },
+			(l) => (l === "a.png" ? "file:///tmp/mock%20dir/a.png" : undefined),
+			0,
+		);
+		expect(links).toHaveLength(1);
+		expect(links[0].text).toBe("file:///tmp/mock%20dir/a.png");
+	});
+
 	it("stitches a wrapped link across rows to resolve the full label", () => {
 		// Row 3 ends with "#12" (id 4), row 4 starts with "34" (id 4).
 		const top = "text #12";
@@ -291,3 +339,57 @@ describe("safeHttpUri", () => {
 		expect(safeHttpUri("https://")).toBeUndefined();
 	});
 });
+
+describe("safeFileUri", () => {
+	it("accepts local file URIs, empty or localhost host", () => {
+		expect(safeFileUri("file:///tmp/a.png")).toBe("file:///tmp/a.png");
+		expect(safeFileUri("file://localhost/tmp/a.png")).toBe("file://localhost/tmp/a.png");
+	});
+
+	it("rejects remote hosts, other schemes, and control characters", () => {
+		expect(safeFileUri("file://evil.example/share/x")).toBeUndefined();
+		expect(safeFileUri("https://a.dev")).toBeUndefined();
+		expect(safeFileUri("file:///tmp/a b.png")).toBeUndefined();
+		expect(safeFileUri("file:///tmp/a\nb.png")).toBeUndefined();
+	});
+});
+
+describe("fileUriToLocalPath", () => {
+	it("converts a pathToFileURL-style URI back to a path", () => {
+		expect(fileUriToLocalPath("file:///tmp/mock-cc-global.png")).toEqual({ path: "/tmp/mock-cc-global.png" });
+	});
+
+	it("percent-decodes the path", () => {
+		expect(fileUriToLocalPath("file:///tmp/mock%20dir/a.png")).toEqual({ path: "/tmp/mock dir/a.png" });
+	});
+
+	it("strips the leading slash of a Windows drive path", () => {
+		expect(fileUriToLocalPath("file:///C:/dir/file.ts")).toEqual({ path: "C:/dir/file.ts" });
+	});
+
+	it("carries a trailing :line[:col] suffix out separately", () => {
+		expect(fileUriToLocalPath("file:///a/b.ts:12")).toEqual({ path: "/a/b.ts", line: 12 });
+		expect(fileUriToLocalPath("file:///a/b.ts:12:5")).toEqual({ path: "/a/b.ts", line: 12 });
+	});
+
+	it("rejects a path whose decoding re-introduces a control character", () => {
+		// safeFileUri sees the encoded form and passes it; the NUL and the
+		// newline only exist after decodeURIComponent. A space is legitimate.
+		expect(fileUriToLocalPath("file:///tmp/a%00b")).toBeUndefined();
+		expect(fileUriToLocalPath("file:///tmp/a%0Ab")).toBeUndefined();
+		expect(fileUriToLocalPath("file:///tmp/a%20b")).toEqual({ path: "/tmp/a b" });
+	});
+
+	it("leaves an absurd line suffix as part of the path instead of parsing it", () => {
+		expect(fileUriToLocalPath("file:///a/b.ts:99999999999999999999")).toEqual({
+			path: "/a/b.ts:99999999999999999999",
+		});
+		expect(fileUriToLocalPath("file:///a/b.ts:999999999")).toEqual({ path: "/a/b.ts", line: 999_999_999 });
+	});
+
+	it("rejects what safeFileUri rejects, and undecodable paths", () => {
+		expect(fileUriToLocalPath("https://a.dev/x")).toBeUndefined();
+		expect(fileUriToLocalPath("file://evil.example/x")).toBeUndefined();
+		expect(fileUriToLocalPath("file:///tmp/%zz")).toBeUndefined();
+	});
+});

src/mainview/__tests__/terminal-path-open.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { activateOsc8Uri, OPEN_FILE_PREVIEW_EVENT, type OpenFilePreviewDetail } from "../terminal-path-open";
+import { api } from "../rpc";
+import { toast } from "../toast";
+
+vi.mock("../rpc", () => ({
+	isElectrobun: false,
+	api: {
+		request: {
+			resolveTerminalPaths: vi.fn(),
+			getGlobalSettings: vi.fn(),
+			openTerminalPath: vi.fn(),
+		},
+	},
+}));
+
+vi.mock("../toast", () => ({
+	toast: { error: vi.fn(), info: vi.fn(), success: vi.fn() },
+}));
+
+const resolveTerminalPaths = api.request.resolveTerminalPaths as unknown as ReturnType<typeof vi.fn>;
+const t = ((key: string, vars?: Record<string, string>) =>
+	`${key}:${JSON.stringify(vars ?? {})}`) as unknown as Parameters<typeof activateOsc8Uri>[1]["t"];
+
+function previewed(): Promise<OpenFilePreviewDetail> {
+	return new Promise((resolve) => {
+		window.addEventListener(
+			OPEN_FILE_PREVIEW_EVENT,
+			(event) => resolve((event as CustomEvent<OpenFilePreviewDetail>).detail),
+			{ once: true },
+		);
+	});
+}
+
+describe("activateOsc8Uri", () => {
+	beforeEach(() => {
+		vi.clearAllMocks();
+	});
+
+	it("opens a resolved file URI through the backend gate, carrying the line", async () => {
+		resolveTerminalPaths.mockResolvedValue({ resolved: { "/repo/src/a.ts": { path: "/repo/src/a.ts", kind: "file" } } });
+		const detail = previewed();
+		await activateOsc8Uri("file:///repo/src/a.ts:12:5", { t, taskId: "task-1", projectId: "proj-1" });
+		expect(resolveTerminalPaths).toHaveBeenCalledWith({ taskId: "task-1", projectId: "proj-1", paths: ["/repo/src/a.ts"] });
+		expect(await detail).toEqual({ path: "/repo/src/a.ts", line: 12, taskId: "task-1" });
+	});
+
+	it("says so when the backend refuses the path, and opens nothing", async () => {
+		resolveTerminalPaths.mockResolvedValue({ resolved: { "/etc/passwd": null } });
+		const open = vi.spyOn(window, "open").mockReturnValue(null);
+		await activateOsc8Uri("file:///etc/passwd", { t });
+		expect(open).not.toHaveBeenCalled();
+		expect(toast.error).toHaveBeenCalledWith(expect.stringContaining("terminal.fileLinkNotFound"), expect.anything());
+		open.mockRestore();
+	});
+
+	it("never hands a file URI to window.open when it cannot become a path", async () => {
+		const open = vi.spyOn(window, "open").mockReturnValue(null);
+		await activateOsc8Uri("file:///tmp/%zz", { t });
+		expect(open).not.toHaveBeenCalled();
+		expect(resolveTerminalPaths).not.toHaveBeenCalled();
+		expect(toast.error).toHaveBeenCalledWith(expect.stringContaining("terminal.fileLinkUnreadable"), expect.anything());
+		open.mockRestore();
+	});
+
+	it("opens a non-file URI externally", async () => {
+		const open = vi.spyOn(window, "open").mockReturnValue(null);
+		await activateOsc8Uri("https://example.com/pr/1", { t });
+		expect(open).toHaveBeenCalledWith("https://example.com/pr/1", "_blank", "noopener,noreferrer");
+		expect(resolveTerminalPaths).not.toHaveBeenCalled();
+		open.mockRestore();
+	});
+
+	it("reports a failed resolve instead of throwing into the click handler", async () => {
+		resolveTerminalPaths.mockRejectedValue(new Error("rpc down"));
+		await activateOsc8Uri("file:///repo/a.ts", { t });
+		expect(toast.error).toHaveBeenCalledWith(expect.stringContaining("terminal.pathLinkOpenFailed"), expect.anything());
+	});
+});

src/mainview/i18n/translations/en/terminal.ts

@@ -248,6 +248,8 @@ const terminal = {
 	// File path links in terminal output (Cmd/Ctrl+Click)
 	"terminal.pathLinkFolderBrowser": "Folders can't be opened from the browser — use the desktop app.",
 	"terminal.pathLinkOpenFailed": "Couldn't open path: {error}",
+	"terminal.fileLinkNotFound": "Can't open {path} — it's missing, or outside the allowed folders.",
+	"terminal.fileLinkUnreadable": "That link isn't a readable file path: {uri}",
 	"terminal.filePreviewLoading": "Loading preview…",
 	"terminal.filePreviewNotFound": "File not found — it may have been moved or deleted.",
 	"terminal.filePreviewBinary": "Binary file ({size}) — no preview available.",

src/mainview/i18n/translations/es/terminal.ts

@@ -248,6 +248,8 @@ const terminal = {
 	// File path links in terminal output (Cmd/Ctrl+Click)
 	"terminal.pathLinkFolderBrowser": "Las carpetas no se pueden abrir desde el navegador — usa la aplicación de escritorio.",
 	"terminal.pathLinkOpenFailed": "No se pudo abrir la ruta: {error}",
+	"terminal.fileLinkNotFound": "No se puede abrir {path}: no existe o está fuera de las carpetas permitidas.",
+	"terminal.fileLinkUnreadable": "Ese enlace no es una ruta de archivo legible: {uri}",
 	"terminal.filePreviewLoading": "Cargando vista previa…",
 	"terminal.filePreviewNotFound": "Archivo no encontrado — puede que se haya movido o eliminado.",
 	"terminal.filePreviewBinary": "Archivo binario ({size}) — vista previa no disponible.",

src/mainview/i18n/translations/ru/terminal.ts

@@ -258,6 +258,8 @@ const terminal = {
 	// File path links in terminal output (Cmd/Ctrl+Click)
 	"terminal.pathLinkFolderBrowser": "Папки нельзя открыть из браузера — используйте настольное приложение.",
 	"terminal.pathLinkOpenFailed": "Не удалось открыть путь: {error}",
+	"terminal.fileLinkNotFound": "Не удалось открыть {path} — файла нет или он вне разрешённых папок.",
+	"terminal.fileLinkUnreadable": "Эта ссылка не похожа на путь к файлу: {uri}",
 	"terminal.filePreviewLoading": "Загрузка предпросмотра…",
 	"terminal.filePreviewNotFound": "Файл не найден — возможно, его переместили или удалили.",
 	"terminal.filePreviewBinary": "Двоичный файл ({size}) — предпросмотр недоступен.",

src/mainview/terminal-cell-hit.ts

@@ -0,0 +1,27 @@
+import type { Terminal } from "ghostty-web";
+import { viewportRowToAbsolute } from "./terminal-link-underlines";
+
+/** A terminal cell under the pointer: absolute buffer row, viewport column. */
+export interface TerminalCell {
+	y: number;
+	x: number;
+	/** The same row counted from the top of the viewport, for positioning. */
+	viewportRow: number;
+}
+
+/**
+ * The cell a mouse event points at, or undefined when it lands outside the
+ * grid. Same math ghostty-web's own click handler uses, shared by the OSC 8
+ * hover tooltip and the OSC 8 click so both read the same cell.
+ */
+export function cellFromMouseEvent(term: Terminal, event: MouseEvent): TerminalCell | undefined {
+	const renderer = term.renderer;
+	const canvas = renderer?.getCanvas();
+	if (!renderer || !canvas || !renderer.charWidth || !renderer.charHeight) return undefined;
+	const rect = canvas.getBoundingClientRect();
+	const x = Math.floor((event.clientX - rect.left) / renderer.charWidth);
+	const viewportRow = Math.floor((event.clientY - rect.top) / renderer.charHeight);
+	if (x < 0 || x >= term.cols || viewportRow < 0 || viewportRow >= term.rows) return undefined;
+	const scrollback = Math.max(0, term.buffer.active.length - term.rows);
+	return { y: viewportRowToAbsolute(viewportRow, term.viewportY, scrollback), x, viewportRow };
+}