@yinan_chen/pi-claude-code-ui 0.0.0-stage → 0.2.0

package/src/index.ts

@@ -0,0 +1,566 @@
+/**
+ * lean-tidy — Claude transcript adapter with a Pi-native fallback.
+ *
+ * Rendering lives in claude-view.ts; this entry point owns configuration,
+ * built-in tool execution/renderers, reload-safe prototype trampolines and F5.
+ * A trampoline reads __leanTidyImpl on every invocation, so /reload replaces
+ * behavior without wrapping the same Pi class twice. The original FLAG names
+ * are intentionally stable for an already-running Pi process.
+ */
+import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import {
+	ToolExecutionComponent,
+	createReadToolDefinition,
+	createBashToolDefinition,
+	createEditToolDefinition,
+	createWriteToolDefinition,
+	createGrepToolDefinition,
+	createFindToolDefinition,
+	createLsToolDefinition,
+	generateDiffString,
+} from "@earendil-works/pi-coding-agent";
+import { mkdir, readFile, writeFile as fsWriteFile } from "node:fs/promises";
+import { appendFileSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { Container } from "@earendil-works/pi-tui";
+import { getPiRuntime, VERIFIED_PI_VERSION } from "./pi-runtime.ts";
+import { createClaudeView } from "./claude-view.ts";
+import registerSubagentPanels from "./subagent-panel.ts";
+import stickyFirstMessage from "./sticky-first-message.ts";
+import registerSkillRecollapse from "./skill-block-recollapse.ts";
+import registerWorkingMessage from "./working-message.ts";
+// Vendored rich diff (MIT; see vendor/diff/ATTRIBUTION.md).
+import { renderRichToolResult, WriteExecutionMetadataStore } from "./vendor/diff/index.ts";
+import { DEFAULT_TOOL_DISPLAY_CONFIG, type ToolDisplayConfig } from "./vendor/diff-config.ts";
+
+const LOG = "/tmp/lean-tidy.log";
+const DEBUG = (process.env.PI_LEAN_TIDY_DEBUG || "").trim() === "1";
+const AGENT_DIR = process.env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent");
+const CONFIG_PATH = join(AGENT_DIR, "lean-tidy.json");
+const TOOLS = ["read", "bash", "edit", "write", "grep", "find", "ls"] as const;
+const IMPL_KEY = "__leanTidyImpl";
+const writeMeta = new WriteExecutionMetadataStore();
+let diffDisplayConfig: ToolDisplayConfig = { ...DEFAULT_TOOL_DISPLAY_CONFIG };
+let THEME: any = (globalThis as any).__leanTidyTheme;
+let LAST_MODE: any;
+const loadCounter = ((globalThis as any).__leanTidyLoadCounter ?? 0) + 1;
+(globalThis as any).__leanTidyLoadCounter = loadCounter;
+
+function diag(...parts: unknown[]): void {
+	if (!DEBUG) return;
+	try {
+		appendFileSync(LOG, `${parts.map((part) => typeof part === "string" ? part : JSON.stringify(part)).join(" ")}\n`);
+	} catch {}
+}
+
+function captureTheme(theme: any): void {
+	if (theme && typeof theme.fg === "function" && THEME !== theme) {
+		THEME = theme;
+		(globalThis as any).__leanTidyTheme = theme;
+	}
+}
+
+/** Only options used by the Claude adapter are read; obsolete settings are ignored. */
+interface Config {
+	profile: "claude" | "native";
+	/** Skill 调用块样式：native = pi 原生 [skill] name 折叠行（默认）；claude = ● Skill(name) 两行风格。 */
+	skillRendering: "native" | "claude";
+	/** Subagent 完成通知（@tintinweb/pi-subagents 的 subagent-notification）样式：
+	 * claude = ● Subagent(desc) + ⎿ 分支风格（默认）；native = 保留包内面板。 */
+	subagentRendering: "native" | "claude";
+	detailsBackground: string;
+	bashPreviewLines: number;
+	codePreviewLines: number;
+	errorPreviewLines: number;
+	liveThinking: boolean;
+	thinkingTailLines: number;
+	foldAnimMs: number;
+}
+
+function loadConfig(): Config {
+	const config: Config = {
+		profile: "claude",
+		skillRendering: "native",
+		subagentRendering: "claude",
+		detailsBackground: "selectedBg",
+		bashPreviewLines: 1,
+		codePreviewLines: 3,
+		errorPreviewLines: 1,
+		liveThinking: true,
+		thinkingTailLines: 3,
+		foldAnimMs: 240,
+	};
+	diffDisplayConfig = { ...DEFAULT_TOOL_DISPLAY_CONFIG };
+	try {
+		const data = JSON.parse(readFileSync(CONFIG_PATH, "utf8"));
+		if (data?.profile === "claude" || data?.profile === "native") config.profile = data.profile;
+		if (data?.skillRendering === "claude" || data?.skillRendering === "native") config.skillRendering = data.skillRendering;
+		if (data?.subagentRendering === "claude" || data?.subagentRendering === "native") config.subagentRendering = data.subagentRendering;
+		if (["selectedBg", "customMessageBg", "toolPendingBg", "toolSuccessBg", "toolErrorBg", ""].includes(data?.detailsBackground)) {
+			config.detailsBackground = data.detailsBackground;
+		}
+		for (const key of ["bashPreviewLines", "codePreviewLines", "errorPreviewLines"] as const) {
+			if (Number.isInteger(data?.[key]) && data[key] >= 0 && data[key] <= 100) config[key] = data[key];
+		}
+		if (typeof data?.liveThinking === "boolean") config.liveThinking = data.liveThinking;
+		if (Number.isFinite(data?.thinkingTailLines) && data.thinkingTailLines >= 0) {
+			config.thinkingTailLines = Math.floor(data.thinkingTailLines);
+		}
+		if (Number.isFinite(data?.foldAnimMs) && data.foldAnimMs >= 0) config.foldAnimMs = Math.floor(data.foldAnimMs);
+		if (data?.diff && typeof data.diff === "object" && !Array.isArray(data.diff)) {
+			diffDisplayConfig = { ...DEFAULT_TOOL_DISPLAY_CONFIG, ...data.diff };
+		}
+	} catch {}
+	const profile = (process.env.PI_LEAN_TIDY_PROFILE || "").trim();
+	if (profile === "claude" || profile === "native") config.profile = profile;
+	const skill = (process.env.PI_LEAN_TIDY_SKILL || "").trim();
+	if (skill === "claude" || skill === "native") config.skillRendering = skill;
+	const subagent = (process.env.PI_LEAN_TIDY_SUBAGENT || "").trim();
+	if (subagent === "claude" || subagent === "native") config.subagentRendering = subagent;
+	const live = (process.env.PI_LEAN_TIDY_LIVE_THINKING || "").trim().toLowerCase();
+	if (live === "on" || live === "off") config.liveThinking = live === "on";
+	if ((process.env.PI_TIDY_STATIC_THINKING || "").trim() === "1") config.liveThinking = false;
+	const tail = (process.env.PI_LEAN_TIDY_THINKING_TAIL || "").trim();
+	if (/^\d+$/.test(tail)) config.thinkingTailLines = Number(tail);
+	return config;
+}
+
+/** Global settings are safe to read; project settings require explicit project trust. */
+function readBuiltinToolOptions(cwd?: string, trusted = false): { read: any; bash: any; key: string } {
+	const readJson = (path: string): any => {
+		try { return JSON.parse(readFileSync(path, "utf8")); } catch { return undefined; }
+	};
+	const globalSettings = readJson(join(AGENT_DIR, "settings.json")) ?? {};
+	const projectSettings = cwd && trusted ? (readJson(join(cwd, ".pi", "settings.json")) ?? {}) : {};
+	const pick = <T>(get: (settings: any) => T): T | undefined => {
+		const projectValue = get(projectSettings);
+		return projectValue !== undefined ? projectValue : get(globalSettings);
+	};
+	const opts = {
+		read: { autoResizeImages: pick((s) => s?.images?.autoResize) ?? true },
+		bash: { commandPrefix: pick((s) => s?.shellCommandPrefix), shellPath: pick((s) => s?.shellPath) },
+	};
+	return { ...opts, key: JSON.stringify(opts) };
+}
+
+/** Leave the native renderer intact: Claude owns transcript presentation, not tool execution. */
+function richDiffComponent(tool: any, expanded: boolean, theme: any, invalidate: () => void): any | undefined {
+	const name = String(tool.toolName ?? "");
+	if ((name !== "edit" && name !== "write") || !theme || tool.result?.isError) return undefined;
+	const result = tool.result;
+	const hasDiff = typeof result?.details?.diff === "string" && result.details.diff.trim().length > 0;
+	if (name === "edit" && !hasDiff) return undefined;
+	const toolCallId = String(tool.toolCallId ?? "");
+	if (name === "write" && !writeMeta.get(toolCallId)) return undefined;
+	try {
+		return renderRichToolResult(
+			name,
+			result,
+			{ isPartial: false, isError: false, expanded, isHovered: () => false, invalidate },
+			theme,
+			{ args: tool.args ?? {}, toolCallId, invalidate, isError: false, expanded },
+			writeMeta,
+			diffDisplayConfig,
+		);
+	} catch { return undefined; }
+}
+
+const IMPL_METHODS = [
+	"toolExecRender", "toolExecHandleMouse", "assistantRender", "assistantUpdateContent",
+	"genericRender", "modeRenderInitial", "modeAddMessage", "modeSetToolsExpanded",
+	"modeUpdateThinkingVisibility", "modeHandleEvent",
+] as const;
+type ImplMethod = typeof IMPL_METHODS[number];
+type RuntimeImpl = {
+	loadId: number;
+	config: Config;
+	hookMode(mode: any): void;
+	containerRender(container: any, width: number, chat: boolean): string[];
+} & Record<ImplMethod, (self: any, orig: (...args: any[]) => any, ...args: any[]) => any>;
+
+function getImpl(): RuntimeImpl | undefined {
+	return (globalThis as any)[IMPL_KEY];
+}
+
+/** Unwind instance-only hooks left by an in-process /reload before native rendering. */
+function restoreNativeMode(mode: any): void {
+	const chat = mode?.chatContainer;
+	if (!chat) return;
+	if (chat.__tidyNoSpacers) {
+		if (chat.addChild?.name === "leanTidyAddChild") chat.addChild = Container.prototype.addChild;
+		for (const child of chat.children ?? []) {
+			if (typeof child?.setLines === "function" && child.lines === 0) child.setLines(1);
+		}
+		delete chat.__tidyNoSpacers;
+	}
+	if (chat.__tidyRenderWrapped && chat.render?.name === "leanTidyChatRender") {
+		chat.render = Container.prototype.render;
+		delete chat.__tidyRenderWrapped;
+	}
+	// Claude's instance wrapper also survives /reload; do not leave a stale
+	// adapter dispatch in the native profile even though its fallback works.
+	if (chat.__claudeChatWrapped) {
+		const original = Symbol.for("lean-tidy/claude-original-render");
+		chat.render = chat[original] ?? Container.prototype.render;
+		delete chat[original];
+		delete chat.__claudeChatWrapped;
+	}
+	for (const child of chat.children ?? []) {
+		const content = child?.contentContainer;
+		if (content?.__leanTidyFilteredContainer) {
+			content.render = Container.prototype.render;
+			delete content.__leanTidyFilteredContainer;
+		}
+	}
+}
+
+// Stable FLAG names are essential: old trampolines also call getImpl() after /reload.
+const FLAG_TOOLEXEC = "__tidyAnytoolPatched";
+const FLAG_ASSISTANT = "__tidyAnytoolAssistantPatched";
+const FLAG_LIVE = "__tidyAnytoolLiveThinkingPatched";
+const FLAG_USERMSG = "__tidyAnytoolUserMsgPatched";
+const FLAG_SKILL = "__tidyAnytoolSkillPatched";
+const FLAG_INTERACTIVE = "__tidyAnytoolInteractivePatched";
+const FILTER_KEYS: [string, string][] = [
+	["BashExecutionComponent", "__tidyAnytoolBashExecPatched"],
+	["CustomMessageComponent", "__tidyAnytoolCustomMsgPatched"],
+	["CompactionSummaryMessageComponent", "__tidyAnytoolCompactionPatched"],
+	["BranchSummaryMessageComponent", "__tidyAnytoolBranchPatched"],
+	["CustomEntryComponent", "__tidyAnytoolCustomEntryPatched"],
+];
+const patchedProtos = new Set<any>();
+
+function trampoline(proto: any, method: string, implMethod: ImplMethod): boolean {
+	const orig = proto?.[method];
+	if (typeof orig !== "function") return false;
+	const wrapper = function (this: any, ...args: any[]) {
+		const impl = getImpl();
+		if (!impl) return orig.apply(this, args);
+		try { return impl[implMethod](this, orig, ...args); }
+		catch (error: any) {
+			diag("impl error:", implMethod, error?.message);
+			return orig.apply(this, args);
+		}
+	};
+	try { Object.defineProperty(wrapper, "name", { value: `leanTidy_${implMethod}` }); } catch {}
+	proto[method] = wrapper;
+	return true;
+}
+
+function once(proto: any, flag: string): boolean {
+	if (!proto || proto[flag]) return false;
+	proto[flag] = true;
+	return true;
+}
+
+function patchToolExec(cls: any): boolean {
+	const proto = cls?.prototype;
+	if (!proto || typeof proto.render !== "function" || typeof proto.updateDisplay !== "function" || typeof proto.setExpanded !== "function") return false;
+	if (!once(proto, FLAG_TOOLEXEC)) return false;
+	trampoline(proto, "render", "toolExecRender");
+	trampoline(proto, "handleMouse", "toolExecHandleMouse");
+	patchedProtos.add(proto);
+	return true;
+}
+
+function patchAssistant(cls: any): boolean {
+	const proto = cls?.prototype;
+	if (!proto || typeof proto.render !== "function" || typeof proto.updateContent !== "function" || typeof proto.setOutputPad !== "function") return false;
+	let did = false;
+	if (once(proto, FLAG_ASSISTANT)) did = trampoline(proto, "render", "assistantRender") || did;
+	if (once(proto, FLAG_LIVE)) did = trampoline(proto, "updateContent", "assistantUpdateContent") || did;
+	if (did) patchedProtos.add(proto);
+	return did;
+}
+
+function patchUserMessage(cls: any): boolean {
+	const proto = cls?.prototype;
+	if (!proto || typeof proto.render !== "function" || typeof proto.rebuild !== "function") return false;
+	if (!once(proto, FLAG_USERMSG)) return false;
+	trampoline(proto, "render", "genericRender");
+	patchedProtos.add(proto);
+	return true;
+}
+
+function patchSkill(cls: any): boolean {
+	const proto = cls?.prototype;
+	if (!proto || typeof proto.render !== "function" || typeof proto.updateDisplay !== "function" || typeof proto.setExpanded !== "function") return false;
+	if (!once(proto, FLAG_SKILL)) return false;
+	trampoline(proto, "render", "genericRender");
+	patchedProtos.add(proto);
+	return true;
+}
+
+function patchFilterOnly(cls: any, flag: string): boolean {
+	const proto = cls?.prototype;
+	if (!proto || typeof proto.render !== "function") return false;
+	if (!once(proto, flag)) return false;
+	trampoline(proto, "render", "genericRender");
+	patchedProtos.add(proto);
+	return true;
+}
+
+function patchInteractive(cls: any): boolean {
+	const proto = cls?.prototype;
+	if (!proto || typeof proto.renderInitialMessages !== "function" || typeof proto.addMessageToChat !== "function") return false;
+	let did = false;
+	if (once(proto, FLAG_INTERACTIVE)) {
+		trampoline(proto, "renderInitialMessages", "modeRenderInitial");
+		trampoline(proto, "addMessageToChat", "modeAddMessage");
+		trampoline(proto, "handleEvent", "modeHandleEvent");
+		did = true;
+	}
+	// A live /reload can add these two entry points to an already-patched class.
+	if (once(proto, "__leanTidyToolsExpansionPatched")) {
+		did = trampoline(proto, "setToolsExpanded", "modeSetToolsExpanded") || did;
+	}
+	if (once(proto, "__leanTidyThinkingVisibilityPatched")) {
+		did = trampoline(proto, "updateThinkingBlockVisibility", "modeUpdateThinkingVisibility") || did;
+	}
+	if (did) patchedProtos.add(proto);
+	return did;
+}
+
+function patchModule(mod: any, where: string): number {
+	let n = 0;
+	for (const key of Object.keys(mod)) {
+		let cls: any;
+		try { cls = mod[key]; } catch { continue; }
+		if (typeof cls !== "function") continue;
+		let did = false;
+		if (key.includes("ToolExecution")) did = patchToolExec(cls);
+		else if (key.includes("AssistantMessage")) did = patchAssistant(cls);
+		else if (key.includes("UserMessage")) did = patchUserMessage(cls);
+		else if (key.includes("SkillInvocation")) did = patchSkill(cls);
+		else if (key.includes("InteractiveMode")) did = patchInteractive(cls);
+		else {
+			for (const [name, flag] of FILTER_KEYS) {
+				if (key.includes(name)) { did = patchFilterOnly(cls, flag); break; }
+			}
+		}
+		if (did) { n++; diag("patched:", where, key); }
+	}
+	return n;
+}
+
+interface ScanInfo {
+	pkgRoot: string;
+	piVersion: string;
+	bundleRuntime: boolean;
+	files: string[];
+	patched: number;
+	cacheHit: boolean;
+	ms: number;
+}
+
+async function patchAllCopies(): Promise<ScanInfo> {
+	const start = Date.now();
+	const rt = await getPiRuntime();
+	let patched = 0;
+	for (const { where, mod } of rt.modules) patched += patchModule(mod, where);
+	return {
+		pkgRoot: rt.pkgRoot, piVersion: rt.piVersion, bundleRuntime: rt.bundleRuntime,
+		files: rt.files, patched, cacheHit: rt.cacheHit, ms: Date.now() - start,
+	};
+}
+
+export default async function leanTidy(pi: ExtensionAPI): Promise<void> {
+	registerWorkingMessage(pi);
+	await stickyFirstMessage(pi);
+	registerSkillRecollapse(pi);
+	const config = loadConfig();
+	// Subagent 通知接管必须发生在加载期（registerMessageRenderer 仅 factory 内合法）：
+	// lean-tidy 先于 npm 包加载，首个命中 customType 的渲染器胜出（一南 2026-02-12）。
+	// redraw 闭包延迟读 LAST_MODE（hookMode 后才看得到 TUI）。
+	if (config.subagentRendering === "claude") {
+		registerSubagentPanels(pi, { redraw: () => { LAST_MODE?.ui?.requestRender?.(); } });
+	}
+	if (DEBUG) {
+		try { writeFileSync(LOG, `=== lean-tidy load #${loadCounter} ${new Date().toISOString()} ===\n`); } catch {}
+	}
+	let noticeContext: any;
+	let lastWarning: string | undefined;
+	(globalThis as any).__leanTidyClaude?.dispose?.();
+	const claude = config.profile === "claude" ? createClaudeView(
+		// Keep the same object: runtime foldAnimMs changes must reach the adapter.
+		config,
+		() => THEME,
+		(message) => {
+			lastWarning = message;
+			diag(message);
+			noticeContext?.ui?.notify?.(message, "warning");
+		},
+		richDiffComponent,
+	) : undefined;
+	(globalThis as any).__leanTidyClaude = claude;
+	const hookMode = (mode: any) => {
+		LAST_MODE = mode;
+		if (claude) claude.hookMode(mode);
+		else restoreNativeMode(mode);
+	};
+	const impl = {
+		loadId: loadCounter,
+		config,
+		hookMode,
+		containerRender: (container: any, width: number, chat: boolean): string[] =>
+			claude && chat ? claude.renderChat(container, width) : Container.prototype.render.call(container, width),
+	} as RuntimeImpl;
+	for (const method of IMPL_METHODS) {
+		impl[method] = (self, orig, ...args) => {
+			if (!claude) {
+				if (method === "modeRenderInitial" || method === "modeAddMessage" || method === "modeHandleEvent") hookMode(self);
+				return orig.apply(self, args);
+			}
+			try { return (claude[method] as (...parts: any[]) => any)(self, orig, ...args); }
+			catch (error) { claude.fail(error); return orig.apply(self, args); }
+		};
+	}
+	(globalThis as any)[IMPL_KEY] = impl;
+
+	let scan: ScanInfo | undefined;
+	try {
+		scan = await patchAllCopies();
+		diag("scan:", scan);
+	} catch (error: any) { diag("scan error:", error?.message); }
+
+	let registeredOptsKey = "";
+	let probeDef: ToolDefinition | undefined;
+	/** Construct a detached tool to capture Pi's theme before transcript rendering. */
+	function probeTheme(cwd: string): void {
+		if (THEME || !probeDef) return;
+		try {
+			new ToolExecutionComponent("read", "__lean_tidy_theme_probe__", { path: "" }, {}, probeDef, { requestRender() {} } as any, cwd);
+		} catch (error: any) { diag("theme probe failed:", error?.message); }
+	}
+
+	/** Register before session_start: the first historical render may happen earlier. */
+	function registerTools(cwd: string, trusted = false): void {
+		const opts = readBuiltinToolOptions(cwd, trusted);
+		if (registeredOptsKey === opts.key) return;
+		registeredOptsKey = opts.key;
+		const factories: Record<string, (cwd: string, options?: any) => any> = {
+			read: (dir) => createReadToolDefinition(dir, opts.read),
+			bash: (dir) => createBashToolDefinition(dir, opts.bash),
+			edit: (dir) => createEditToolDefinition(dir),
+			write: (dir, options) => createWriteToolDefinition(dir, options),
+			grep: (dir) => createGrepToolDefinition(dir),
+			find: (dir) => createFindToolDefinition(dir),
+			ls: (dir) => createLsToolDefinition(dir),
+		};
+		for (const name of TOOLS) {
+			let orig: any;
+			try { orig = factories[name](cwd); }
+			catch (error: any) { diag("factory failed:", name, error?.message); continue; }
+			// Pi's write tool owns the file-mutation queue; operations execute inside it.
+			const execute = name === "write"
+				? async (id: string, params: any, signal: any, onUpdate: any, ctx: any) => {
+					let diff = "";
+					let created = false;
+					let previousContent = "";
+					const writeTool = factories.write(cwd, {
+						operations: {
+							mkdir: async (directory: string) => { await mkdir(directory, { recursive: true }); },
+							writeFile: async (path: string, content: string) => {
+								let previous = "";
+								try { previous = await readFile(path, "utf8"); }
+								catch (error: any) {
+									if (error?.code !== "ENOENT") throw error;
+									created = true;
+								}
+								previousContent = previous;
+								await mkdir(dirname(path), { recursive: true });
+								await fsWriteFile(path, content, "utf8");
+								diff = generateDiffString(previous, content).diff;
+							},
+						},
+					});
+					const result = await (writeTool.execute as (...args: any[]) => any).call(writeTool, id, params, signal, onUpdate, ctx);
+					const oversized = previousContent.length > 512_000 ||
+						(typeof params?.content === "string" && params.content.length > 512_000);
+					writeMeta.set(id, {
+						fileExistedBeforeWrite: !created,
+						previousContent,
+						diffUnavailableReason: oversized ? "file exceeds the 512,000-byte diff limit" : undefined,
+					});
+					return { ...result, details: { ...(result.details ?? {}), diff, created } };
+				}
+				: (id: string, params: any, signal: any, onUpdate: any, ctx: any) => orig.execute(id, params, signal, onUpdate, ctx);
+			// Spread preserves promptSnippet, promptGuidelines, constrainedSampling,
+			// prepareArguments and executionMode. Renderers remain Pi-native for fallback.
+			const tool: ToolDefinition = {
+				...orig,
+				execute: execute as ToolDefinition["execute"],
+				renderCall: (args: any, theme: any, context: any) => {
+					captureTheme(theme);
+					const slot = context?.state ?? {};
+					const rendered = orig.renderCall?.(args, theme, { ...context, lastComponent: slot.__claudeNativeCall }) ?? new Container();
+					slot.__claudeNativeCall = rendered;
+					return rendered;
+				},
+				renderResult: (result: any, options: any, theme: any, context: any) => {
+					captureTheme(theme);
+					const slot = context?.state ?? {};
+					const rendered = orig.renderResult?.(result, options, theme, { ...context, lastComponent: slot.__claudeNativeResult }) ?? new Container();
+					slot.__claudeNativeResult = rendered;
+					return rendered;
+				},
+			};
+			pi.registerTool(tool);
+			if (name === "read") probeDef = tool;
+		}
+	}
+
+	pi.on("agent_start", async () => { claude?.onAgentStart(); });
+	pi.on("message_start", async (event: any) => { claude?.onEvent({ ...event, type: "message_start" }); });
+	pi.on("message_update", async (event: any) => { claude?.onEvent({ ...event, type: "message_update" }); });
+	pi.on("message_end", async (event: any) => { claude?.onEvent({ ...event, type: "message_end" }); });
+	pi.on("agent_settled", async () => { claude?.onSettled(); });
+	pi.on("session_shutdown", async () => { claude?.dispose(); });
+
+	/** Reset Pi's diff renderer without changing the current session or transcript. */
+	function forceRedraw(): boolean {
+		const tui: any = LAST_MODE?.ui;
+		if (!tui) return false;
+		try {
+			if ("previousScreen" in tui) tui.previousScreen = [];
+			else tui.previousWidth = 1;
+			tui.requestRender?.();
+			return true;
+		} catch { return false; }
+	}
+	pi.registerCommand("tidy-redraw", {
+		description: "lean-tidy: 强制整屏重绘（清掉终端/pane 层留下的残影行）",
+		handler: async (_args: string, ctx: any) => {
+			if (!forceRedraw()) ctx.ui?.notify?.("lean-tidy: 拿不到 TUI，无法重绘", "warning");
+		},
+	});
+	pi.registerShortcut("f5" as any, {
+		description: "lean-tidy: 强制整屏重绘",
+		handler: () => { forceRedraw(); },
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		noticeContext = ctx;
+		claude?.onSession();
+		captureTheme(ctx.ui?.theme);
+		registerTools(ctx.cwd ?? process.cwd(), ctx.isProjectTrusted?.() === true);
+		probeTheme(ctx.cwd ?? process.cwd());
+		if (lastWarning) ctx.ui?.notify?.(lastWarning, "warning");
+		const key = `__leanTidyHealthNotified:${scan?.piVersion ?? "?"}`;
+		const global = globalThis as any;
+		if (scan && !global[key]) {
+			global[key] = true;
+			if (scan.patched === 0 && patchedProtos.size === 0 && !(ToolExecutionComponent.prototype as any)[FLAG_TOOLEXEC]) {
+				ctx.ui?.notify?.("lean-tidy: 0 classes patched — rendering falls back to pi native", "warning");
+			} else if ((process.env.PI_PATCH_VERSION_WARN || "").trim() !== "" && scan.piVersion && scan.piVersion !== VERIFIED_PI_VERSION) {
+				// 版本比对警告默认静默（一南 2026-10-04）；上一分支的「0 classes patched」真问题警告不受影响。
+				// VERIFIED_PI_VERSION 与逐版核验记录仍维护在 _shared/pi-runtime.ts，需要时 PI_PATCH_VERSION_WARN=1 查看。
+				ctx.ui?.notify?.(`lean-tidy: pi ${scan.piVersion} ≠ verified ${VERIFIED_PI_VERSION}; run with PI_LEAN_TIDY_DEBUG=1 if rendering looks off`, "warning");
+			}
+		}
+	});
+
+	try { registerTools(process.cwd()); }
+	catch (error: any) { diag("early register failed:", error?.message); }
+}