topchester-ai 0.9.0 → 0.11.0

package/dist/cli.mjs

@@ -15,7 +15,7 @@ import { parse } from "yaml";
 import pino from "pino";
 import picomatch from "picomatch";
 import { uuidv7 } from "uuidv7";
-import { Input, Markdown, ProcessTerminal, TUI, isKeyRelease, isKeyRepeat, matchesKey, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { CURSOR_MARKER, Markdown, ProcessTerminal, TUI, decodeKittyPrintable, isKeyRelease, isKeyRepeat, matchesKey, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
 import { highlight, supportsLanguage } from "cli-highlight";
 //#region src/agent/tools/ai-sdk-tools.ts
 function toAiSdkToolSet(definitions) {
@@ -28,13 +28,20 @@ function toAiSdkToolSet(definitions) {
 //#region src/knowledge/session-overlay.ts
 const overlays = /* @__PURE__ */ new Map();
 function recordAgentFileEdit(workspaceRoot, event) {
+	return recordAgentFileMutation(workspaceRoot, event);
+}
+function recordAgentFileCreate(workspaceRoot, event) {
+	return recordAgentFileMutation(workspaceRoot, event);
+}
+function recordAgentFileMutation(workspaceRoot, event) {
 	const overlay = getOrCreateOverlay(resolve(workspaceRoot));
 	const previous = overlay.dirtyFiles.get(event.path);
 	overlay.drift = "dirty_known";
 	overlay.kbState = "needs_sync";
 	overlay.needsSync = true;
 	overlay.updatedAt = event.timestamp;
-	overlay.editEvents.push(event);
+	overlay.mutationEvents.push(event);
+	if (event.kind === "file_edit") overlay.editEvents.push(event);
 	overlay.dirtyFiles.set(event.path, {
 		path: event.path,
 		source: "agent",
@@ -42,7 +49,7 @@ function recordAgentFileEdit(workspaceRoot, event) {
 		kbState: "needs_sync",
 		l1State: "stale",
 		derivedState: "suspect",
-		beforeHash: previous?.beforeHash ?? event.beforeHash,
+		beforeHash: previous?.beforeHash ?? (event.kind === "file_create" ? void 0 : event.beforeHash),
 		afterHash: event.afterHash,
 		firstChangedLine: event.firstChangedLine,
 		lastEditedAt: event.timestamp,
@@ -59,7 +66,8 @@ function getOrCreateOverlay(workspaceRoot) {
 		kbState: "current",
 		needsSync: false,
 		dirtyFiles: /* @__PURE__ */ new Map(),
-		editEvents: []
+		editEvents: [],
+		mutationEvents: []
 	};
 	overlays.set(workspaceRoot, overlay);
 	return overlay;
@@ -72,6 +80,7 @@ function snapshotOverlay(overlay) {
 		needsSync: overlay.needsSync,
 		dirtyFiles: [...overlay.dirtyFiles.values()].map((file) => ({ ...file })),
 		editEvents: overlay.editEvents.map((event) => ({ ...event })),
+		mutationEvents: overlay.mutationEvents.map((event) => ({ ...event })),
 		updatedAt: overlay.updatedAt
 	};
 }
@@ -88,37 +97,40 @@ async function enqueueFileMutation(path, mutate) {
 }
 //#endregion
 //#region src/agent/tools/types.ts
+function isToolErrorResult(result) {
+	return "error" in result && typeof result.error === "string";
+}
 function defineTool(definition) {
 	return definition;
 }
 //#endregion
 //#region src/agent/tools/edit-file.ts
 const editFileEditSchema = z.object({
-	old_text: z.string(),
-	new_text: z.string()
+	old_text: z.string().describe("Exact current file text to replace; include whitespace exactly."),
+	new_text: z.string().describe("Replacement text for old_text.")
 });
 const editFileTool = defineTool({
 	name: "edit_file",
-	description: "Edit an existing UTF-8 file inside the workspace with exact text replacements.",
-	prompt: "edit_file: edit an existing UTF-8 file inside the workspace with exact old_text/new_text replacements; read the file first, keep old_text small but unique, and make multiple disjoint edits for one file in one call. To use it, reply with only JSON: {\"tool\":\"edit_file\",\"args\":{\"path\":\"src/example.ts\",\"expected_hash\":\"sha256:optional-current-file-hash\",\"edits\":[{\"old_text\":\"const enabled = false;\\n\",\"new_text\":\"const enabled = true;\\n\"}]}}",
+	description: "Edit an existing UTF-8 file inside the workspace with exact text replacements. Use expected_current_hash only as the current/pre-edit hash from read_file, never as a predicted post-edit hash.",
+	prompt: "edit_file: edit an existing UTF-8 file inside the workspace with exact old_text/new_text replacements; read the file first, keep old_text small but unique, and make multiple disjoint edits for one file in one call. expected_current_hash is optional and must be the current/pre-edit hash returned by the latest read_file for that file; never invent it or use a predicted after-edit hash. To use it, reply with only JSON: {\"tool\":\"edit_file\",\"args\":{\"path\":\"src/example.ts\",\"expected_current_hash\":\"sha256:current-file-hash-from-read_file\",\"edits\":[{\"old_text\":\"const enabled = false;\\n\",\"new_text\":\"const enabled = true;\\n\"}]}}",
 	argsSchema: z.object({
-		path: z.string(),
-		expected_hash: z.string().optional(),
-		edits: z.array(editFileEditSchema).min(1)
+		path: z.string().describe("Workspace-relative path to the existing UTF-8 file to edit."),
+		expected_current_hash: z.string().optional().describe("Optional current file hash returned by the latest read_file result for this file. This is checked before editing to catch stale reads; it is not the hash after the edit."),
+		edits: z.array(editFileEditSchema).min(1).describe("Exact text replacements to apply to the original file.")
 	}),
 	execute: (context, args) => editWorkspaceFile(context.workspaceRoot, args, { logger: context.logger })
 });
 async function editWorkspaceFile(workspaceRoot, args, options = {}) {
-	const scopedPath = resolveWorkspaceScopedPath$3(workspaceRoot, args.path);
+	const scopedPath = resolveWorkspaceScopedPath$4(workspaceRoot, args.path);
 	return enqueueFileMutation(scopedPath.path, async () => {
 		const fileStat = await statExistingFile(scopedPath.path, args.path);
 		const beforeBytes = await readFile(scopedPath.path);
-		const beforeHash = hashBytes(beforeBytes);
-		if (args.expected_hash && args.expected_hash !== beforeHash) throw new Error(`edit_file expected_hash did not match ${scopedPath.relativePath}.`);
-		const result = applyExactEdits(decodeUtf8(scopedPath.relativePath, beforeBytes), args.edits, scopedPath.relativePath);
+		const beforeHash = hashBytes$1(beforeBytes);
+		if (args.expected_current_hash && args.expected_current_hash !== beforeHash) throw new Error(`edit_file expected_current_hash did not match ${scopedPath.relativePath}.`);
+		const result = applyExactEdits(decodeUtf8$1(scopedPath.relativePath, beforeBytes), args.edits, scopedPath.relativePath);
 		const afterBytes = Buffer.from(result.newContent, "utf8");
-		const afterHash = hashBytes(afterBytes);
-		await writeFileAtomically(scopedPath.path, afterBytes, fileStat.mode);
+		const afterHash = hashBytes$1(afterBytes);
+		await writeFileAtomically$1(scopedPath.path, afterBytes, fileStat.mode);
 		const editEvent = {
 			kind: "file_edit",
 			source: "agent",
@@ -172,7 +184,7 @@ function applyExactEdits(content, edits, path = "file") {
 		firstChangedLine: getFirstChangedLine(document.body, newBody)
 	};
 }
-function resolveWorkspaceScopedPath$3(workspaceRoot, path) {
+function resolveWorkspaceScopedPath$4(workspaceRoot, path) {
 	if (path.includes("\0")) throw new Error("edit_file path is invalid.");
 	const resolvedWorkspace = resolve(workspaceRoot);
 	const resolvedPath = isAbsolute(path) ? resolve(path) : resolve(resolvedWorkspace, path);
@@ -189,13 +201,13 @@ async function statExistingFile(resolvedPath, originalPath) {
 	try {
 		fileStat = await stat(resolvedPath);
 	} catch (error) {
-		if (isNodeError$2(error) && error.code === "ENOENT") throw new Error(`edit_file can only edit existing files: ${originalPath}`);
+		if (isNodeError$3(error) && error.code === "ENOENT") throw new Error(`edit_file can only edit existing files: ${originalPath}`);
 		throw error;
 	}
 	if (!fileStat.isFile()) throw new Error(`edit_file can only edit regular files: ${originalPath}`);
 	return fileStat;
 }
-function decodeUtf8(path, bytes) {
+function decodeUtf8$1(path, bytes) {
 	try {
 		return new TextDecoder("utf-8", {
 			fatal: true,
@@ -205,7 +217,7 @@ function decodeUtf8(path, bytes) {
 		throw new Error(`edit_file can only edit UTF-8 text files: ${path}`);
 	}
 }
-async function writeFileAtomically(path, content, mode) {
+async function writeFileAtomically$1(path, content, mode) {
 	const temporaryPath = resolve(dirname(path), `.${basename(path)}.topchester-${process.pid}-${randomUUID()}.tmp`);
 	try {
 		await writeFile(temporaryPath, content, {
@@ -218,7 +230,7 @@ async function writeFileAtomically(path, content, mode) {
 		throw error;
 	}
 }
-function hashBytes(bytes) {
+function hashBytes$1(bytes) {
 	return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
 }
 function summarizeDiff(diff) {
@@ -231,7 +243,7 @@ function summarizeDiff(diff) {
 	}
 	return `+${added}/-${removed}`;
 }
-function isNodeError$2(error) {
+function isNodeError$3(error) {
 	return error instanceof Error && "code" in error;
 }
 function normalizeEdits(edits) {
@@ -367,7 +379,7 @@ const ignoredDirectories = new Set([
 ]);
 const findFileTool = defineTool({
 	name: "find_file",
-	description: "Find files by fuzzy name inside the workspace.",
+	description: "Find files by fuzzy name inside the workspace. Results are file paths, not file contents; use read_file next when the user needs contents.",
 	prompt: "find_file: find existing files by fuzzy path or filename inside the workspace; matches may appear in the middle of a filename, and results are file paths, not file contents. To use it, reply with only JSON: {\"tool\":\"find_file\",\"args\":{\"query\":\"runtime\"}}",
 	argsSchema: findFileArgsSchema,
 	execute: (context, args) => findWorkspaceFilesByName(context.workspaceRoot, args, {
@@ -376,7 +388,7 @@ const findFileTool = defineTool({
 	})
 });
 async function findWorkspaceFilesByName(workspaceRoot, args, options = {}) {
-	const scopedPath = resolveWorkspaceScopedPath$2(workspaceRoot, args.path);
+	const scopedPath = resolveWorkspaceScopedPath$3(workspaceRoot, args.path);
 	const matches = (await collectWorkspaceFiles(scopedPath.workspaceRoot, scopedPath.path, scopedPath.relativePath, options)).map((path) => {
 		const score = scoreFileMatch(args.query, path);
 		return score > 0 ? {
@@ -574,7 +586,7 @@ function scoreSubsequenceMatch(query, value) {
 function normalize(value) {
 	return value.trim().toLowerCase().replaceAll("\\", "/");
 }
-function resolveWorkspaceScopedPath$2(workspaceRoot, path) {
+function resolveWorkspaceScopedPath$3(workspaceRoot, path) {
 	const resolvedWorkspace = resolve(workspaceRoot);
 	const resolvedPath = isAbsolute(path) ? resolve(path) : resolve(resolvedWorkspace, path);
 	const relativePath = relative(resolvedWorkspace, resolvedPath);
@@ -618,6 +630,714 @@ function getExitCode$1(error) {
 function isRecord$3(value) {
 	return typeof value === "object" && value !== null;
 }
+//#endregion
+//#region src/agent/tools/git-runner.ts
+const DEFAULT_TIMEOUT_MS = 1e4;
+const DEFAULT_MAX_OUTPUT_BYTES = 4e4;
+const GIT_FIELD_SEPARATOR = "";
+async function runGit(options) {
+	const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const maxOutputBytes = options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+	const args = [
+		"--no-optional-locks",
+		"-c",
+		"core.quotepath=false",
+		"-c",
+		"core.fsmonitor=false",
+		...options.args
+	];
+	return new Promise((resolveCommand) => {
+		const child = spawn("git", args, {
+			cwd: options.cwd,
+			env: {
+				...process.env,
+				PATH: options.pathEnv ?? process.env.PATH ?? "",
+				GIT_OPTIONAL_LOCKS: "0",
+				GIT_PAGER: "cat",
+				PAGER: "cat",
+				LESS: "-F -X"
+			},
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		const stdoutChunks = [];
+		const stderrChunks = [];
+		let stdoutBytes = 0;
+		let stderrBytes = 0;
+		let truncated = false;
+		let timedOut = false;
+		let settled = false;
+		const timer = setTimeout(() => {
+			timedOut = true;
+			child.kill("SIGTERM");
+			setTimeout(() => {
+				if (!settled) child.kill("SIGKILL");
+			}, 500).unref();
+		}, timeoutMs);
+		child.stdout.on("data", (chunk) => {
+			const appended = appendBoundedChunk(stdoutChunks, stdoutBytes, chunk, maxOutputBytes);
+			stdoutBytes = appended.bytes;
+			truncated = truncated || appended.truncated;
+		});
+		child.stderr.on("data", (chunk) => {
+			const appended = appendBoundedChunk(stderrChunks, stderrBytes, chunk, Math.min(8e3, maxOutputBytes));
+			stderrBytes = appended.bytes;
+			truncated = truncated || appended.truncated;
+		});
+		child.once("error", (error) => {
+			clearTimeout(timer);
+			settled = true;
+			resolveCommand({
+				stdout: "",
+				stderr: error.code === "ENOENT" ? "git is not available on PATH.\n" : `${error.message}\n`,
+				exitCode: 127,
+				timedOut: false,
+				truncated: false,
+				binary: false,
+				missingGit: error.code === "ENOENT"
+			});
+		});
+		child.once("close", (code) => {
+			clearTimeout(timer);
+			settled = true;
+			const stdout = Buffer.concat(stdoutChunks);
+			const stderr = Buffer.concat(stderrChunks);
+			const binary = !options.allowNulOutput && (containsNul(stdout) || containsNul(stderr));
+			resolveCommand({
+				stdout: binary ? "" : stdout.toString("utf8"),
+				stderr: binary ? "git output contained binary data.\n" : stderr.toString("utf8"),
+				exitCode: code ?? (timedOut ? 124 : 1),
+				timedOut,
+				truncated,
+				binary,
+				missingGit: false
+			});
+		});
+	});
+}
+function ensureInsideWorkspace(workspaceRoot, path) {
+	if (path.length === 0 || path.includes("\0")) throw new Error("Git path is invalid.");
+	const resolvedWorkspace = resolve(workspaceRoot);
+	const absolutePath = isAbsolute(path) ? resolve(path) : resolve(resolvedWorkspace, path);
+	const relativePath = relative(resolvedWorkspace, absolutePath);
+	if (relativePath.startsWith("..") || isAbsolute(relativePath)) throw new Error(`Git path must stay inside the workspace: ${path}`);
+	return {
+		workspaceRoot: resolvedWorkspace,
+		absolutePath,
+		relativePath: relativePath || "."
+	};
+}
+async function getRepoInfo(workspaceRoot, pathEnv) {
+	const workspace = await realpath(resolve(workspaceRoot));
+	const root = await runGit({
+		cwd: workspace,
+		pathEnv,
+		args: ["rev-parse", "--show-toplevel"],
+		maxOutputBytes: 8e3
+	});
+	if (root.missingGit) return {
+		available: false,
+		missingGit: true,
+		repoRoot: null,
+		repoRootAbsolute: null,
+		branch: null,
+		head: null,
+		hasHead: false,
+		message: "git is not available on PATH."
+	};
+	if (root.exitCode !== 0) return {
+		available: false,
+		missingGit: false,
+		repoRoot: null,
+		repoRootAbsolute: null,
+		branch: null,
+		head: null,
+		hasHead: false,
+		message: "This workspace is not inside a Git repository."
+	};
+	const repoRootAbsolute = root.stdout.trim();
+	const repoRoot = relative(workspace, repoRootAbsolute) || ".";
+	const hasHead = (await runGit({
+		cwd: workspace,
+		pathEnv,
+		args: [
+			"rev-parse",
+			"--verify",
+			"HEAD"
+		],
+		maxOutputBytes: 8e3
+	})).exitCode === 0;
+	const branchResult = await runGit({
+		cwd: workspace,
+		pathEnv,
+		args: [
+			"symbolic-ref",
+			"--quiet",
+			"--short",
+			"HEAD"
+		],
+		maxOutputBytes: 8e3
+	});
+	const headResult = hasHead ? await runGit({
+		cwd: workspace,
+		pathEnv,
+		args: [
+			"rev-parse",
+			"--short",
+			"HEAD"
+		],
+		maxOutputBytes: 8e3
+	}) : void 0;
+	return {
+		available: true,
+		missingGit: false,
+		repoRoot,
+		repoRootAbsolute,
+		branch: branchResult.exitCode === 0 ? branchResult.stdout.trim() : null,
+		head: headResult?.exitCode === 0 ? headResult.stdout.trim() : null,
+		hasHead
+	};
+}
+function parsePorcelainStatus(output) {
+	return output.split("\0").filter(Boolean).map((entry) => {
+		const indexStatus = entry[0] ?? " ";
+		const worktreeStatus = entry[1] ?? " ";
+		const path = entry.slice(3);
+		const untracked = indexStatus === "?" && worktreeStatus === "?";
+		const staged = !untracked && indexStatus !== " ";
+		const unstaged = !untracked && worktreeStatus !== " ";
+		return {
+			path,
+			indexStatus,
+			worktreeStatus,
+			status: classifyStatus(indexStatus, worktreeStatus),
+			staged,
+			unstaged,
+			untracked
+		};
+	});
+}
+function parseGitLog(output) {
+	return output.split("\n").filter(Boolean).map((line) => {
+		const [sha = "", shortSha = "", timestamp = "0", authorName = "", subject = ""] = line.split(GIT_FIELD_SEPARATOR);
+		return {
+			sha,
+			shortSha,
+			timestamp: Number(timestamp),
+			authorName,
+			subject
+		};
+	});
+}
+function truncateText$1(content, maxBytes) {
+	if (Buffer.byteLength(content) <= maxBytes) return {
+		content,
+		truncated: false
+	};
+	return {
+		content: Buffer.from(content, "utf8").subarray(0, maxBytes).toString("utf8"),
+		truncated: true
+	};
+}
+function gitLogPrettyFormat() {
+	return `%H%x1f%h%x1f%ct%x1f%an%x1f%s`;
+}
+function classifyStatus(indexStatus, worktreeStatus) {
+	if (indexStatus === "?" && worktreeStatus === "?") return "untracked";
+	if (indexStatus === "U" || worktreeStatus === "U" || indexStatus === "A" && worktreeStatus === "A") return "conflicted";
+	if (indexStatus === "R") return "renamed";
+	if (indexStatus === "C") return "copied";
+	if (indexStatus === "D" || worktreeStatus === "D") return "deleted";
+	if (indexStatus === "A") return "added";
+	if (indexStatus === "M" || worktreeStatus === "M") return "modified";
+	return "unknown";
+}
+function appendBoundedChunk(chunks, currentBytes, chunk, maxBytes) {
+	if (currentBytes >= maxBytes) return {
+		bytes: currentBytes,
+		truncated: true
+	};
+	const remaining = maxBytes - currentBytes;
+	const slice = chunk.length > remaining ? chunk.subarray(0, remaining) : chunk;
+	chunks.push(slice);
+	return {
+		bytes: currentBytes + slice.length,
+		truncated: chunk.length > remaining
+	};
+}
+function containsNul(buffer) {
+	return buffer.includes(0);
+}
+//#endregion
+//#region src/agent/tools/git.ts
+const gitStatusValueSchema = z.enum([
+	"added",
+	"modified",
+	"deleted",
+	"renamed",
+	"copied",
+	"untracked",
+	"conflicted",
+	"unknown"
+]);
+const gitStatusArgsSchema = z.object({
+	path: z.string().optional().default("."),
+	include_untracked: z.boolean().optional().default(true)
+});
+const gitDiffArgsSchema = z.object({
+	scope: z.enum([
+		"all",
+		"unstaged",
+		"staged"
+	]).optional().default("all"),
+	path: z.string().optional(),
+	include_untracked: z.boolean().optional().default(false),
+	context_lines: z.number().int().min(0).max(20).optional().default(3),
+	max_bytes: z.number().int().min(1e3).max(2e5).optional().default(4e4)
+});
+const gitLogArgsSchema = z.object({
+	limit: z.number().int().min(1).max(50).optional().default(10),
+	path: z.string().optional()
+});
+const gitAddArgsSchema = z.object({
+	paths: z.array(z.string().min(1)).min(1),
+	expected_status: z.array(z.object({
+		path: z.string().min(1),
+		status: gitStatusValueSchema
+	})).min(1)
+});
+const gitCommitArgsSchema = z.object({
+	message: z.string().trim().min(1).max(500),
+	expected_staged_paths: z.array(z.string().min(1)).min(1)
+});
+const gitStatusTool = defineTool({
+	name: "git_status",
+	description: "Inspect structured Git branch and changed-file status inside the workspace.",
+	prompt: "git_status: inspect branch, head, clean state, staged, unstaged, and untracked files without parsing shell output. To use it, reply with only JSON: {\"tool\":\"git_status\",\"args\":{\"path\":\".\",\"include_untracked\":true}}",
+	argsSchema: gitStatusArgsSchema,
+	execute: (context, args) => inspectGitStatus(context, args)
+});
+const gitDiffTool = defineTool({
+	name: "git_diff",
+	description: "Inspect bounded Git diffs for staged, unstaged, and optionally untracked files.",
+	prompt: "git_diff: inspect a bounded Git diff; use scope \"all\", \"unstaged\", or \"staged\", and include_untracked:true only when untracked file patches are needed. To use it, reply with only JSON: {\"tool\":\"git_diff\",\"args\":{\"scope\":\"all\",\"include_untracked\":true}}",
+	argsSchema: gitDiffArgsSchema,
+	execute: (context, args) => inspectGitDiff(context, args)
+});
+const gitLogTool = defineTool({
+	name: "git_log",
+	description: "Inspect recent Git commits as bounded structured summaries.",
+	prompt: "git_log: inspect recent commits without parsing shell output. To use it, reply with only JSON: {\"tool\":\"git_log\",\"args\":{\"limit\":10,\"path\":\"src/agent/runtime.ts\"}}",
+	argsSchema: gitLogArgsSchema,
+	execute: (context, args) => inspectGitLog(context, args)
+});
+const gitAddTool = defineTool({
+	name: "git_add",
+	description: "Stage explicit changed paths after current Git status has been inspected.",
+	prompt: "git_add: stage only explicit paths the user asked to stage; first inspect git_status, reject broad paths, and pass expected_status for each path. To use it, reply with only JSON: {\"tool\":\"git_add\",\"args\":{\"paths\":[\"src/example.ts\"],\"expected_status\":[{\"path\":\"src/example.ts\",\"status\":\"modified\"}]}}",
+	argsSchema: gitAddArgsSchema,
+	execute: (context, args) => stageGitPaths(context, args)
+});
+const gitCommitTool = defineTool({
+	name: "git_commit",
+	description: "Create a Git commit from exactly the expected staged paths.",
+	prompt: "git_commit: commit only after the user explicitly asks and staged paths exactly match expected_staged_paths. To use it, reply with only JSON: {\"tool\":\"git_commit\",\"args\":{\"message\":\"Add feature\",\"expected_staged_paths\":[\"src/example.ts\"]}}",
+	argsSchema: gitCommitArgsSchema,
+	execute: (context, args) => commitGitPaths(context, args)
+});
+async function inspectGitStatus(context, args) {
+	const repo = await getRepoInfo(context.workspaceRoot, context.pathEnv);
+	const unavailable = formatUnavailable("git_status", repo);
+	if (unavailable) return {
+		...unavailable,
+		branch: null,
+		head: null,
+		hasHead: false,
+		clean: true,
+		files: [],
+		truncated: false
+	};
+	const scopedPath = ensureInsideWorkspace(context.workspaceRoot, args.path);
+	const result = await runGit({
+		cwd: requireRepoRoot(repo),
+		pathEnv: context.pathEnv,
+		allowNulOutput: true,
+		args: [
+			"status",
+			"--porcelain=v1",
+			"-z",
+			"--no-renames",
+			args.include_untracked ? "--untracked-files=all" : "--untracked-files=no",
+			"--",
+			scopedPath.relativePath
+		]
+	});
+	const files = parsePorcelainStatus(result.stdout);
+	return {
+		tool: "git_status",
+		path: scopedPath.relativePath,
+		content: formatGitStatusContent(repo, files),
+		repoRoot: repo.repoRoot,
+		branch: repo.branch,
+		head: repo.head,
+		hasHead: repo.hasHead,
+		clean: files.length === 0,
+		files,
+		truncated: result.truncated,
+		warning: result.truncated ? "git_status output was truncated." : void 0
+	};
+}
+async function inspectGitDiff(context, args) {
+	const repo = await getRepoInfo(context.workspaceRoot, context.pathEnv);
+	const unavailable = formatUnavailable("git_diff", repo);
+	if (unavailable) return {
+		...unavailable,
+		scope: args.scope,
+		path: args.path,
+		fileCount: 0,
+		truncated: false
+	};
+	const repoRoot = requireRepoRoot(repo);
+	const path = args.path ? ensureInsideWorkspace(context.workspaceRoot, args.path).relativePath : void 0;
+	const sections = [];
+	let truncated = false;
+	const changedFiles = /* @__PURE__ */ new Set();
+	if (args.scope === "all" || args.scope === "staged") {
+		const diff = await runDiff(repoRoot, [
+			"diff",
+			"--cached",
+			"--no-ext-diff",
+			"--no-textconv",
+			"--no-renames"
+		], {
+			context,
+			path,
+			contextLines: args.context_lines,
+			maxBytes: args.max_bytes
+		});
+		appendSection(sections, "staged", diff.content);
+		truncated = truncated || diff.truncated;
+		for (const file of await diffNameOnly(repoRoot, true, context, path)) changedFiles.add(file);
+	}
+	if (args.scope === "all" || args.scope === "unstaged") {
+		const diff = await runDiff(repoRoot, [
+			"diff",
+			"--no-ext-diff",
+			"--no-textconv",
+			"--no-renames"
+		], {
+			context,
+			path,
+			contextLines: args.context_lines,
+			maxBytes: args.max_bytes
+		});
+		appendSection(sections, "unstaged", diff.content);
+		truncated = truncated || diff.truncated;
+		for (const file of await diffNameOnly(repoRoot, false, context, path)) changedFiles.add(file);
+	}
+	if (args.include_untracked && args.scope !== "staged") {
+		const untracked = await getUntrackedFiles(repoRoot, context, path);
+		for (const file of untracked) {
+			const diff = await runDiff(repoRoot, [
+				"diff",
+				"--no-index",
+				"--no-ext-diff",
+				"--no-textconv",
+				"--no-renames"
+			], {
+				context,
+				path: void 0,
+				extraPathspecs: ["/dev/null", file],
+				contextLines: args.context_lines,
+				maxBytes: args.max_bytes
+			});
+			appendSection(sections, `untracked ${file}`, diff.content);
+			truncated = truncated || diff.truncated;
+			changedFiles.add(file);
+		}
+	}
+	const bounded = truncateText$1(sections.join("\n").trimEnd() || "No diff.", args.max_bytes);
+	return {
+		tool: "git_diff",
+		path: path ?? void 0,
+		content: bounded.content,
+		repoRoot: repo.repoRoot,
+		scope: args.scope,
+		fileCount: changedFiles.size,
+		truncated: truncated || bounded.truncated,
+		warning: truncated || bounded.truncated ? "git_diff output was truncated." : void 0
+	};
+}
+async function inspectGitLog(context, args) {
+	const repo = await getRepoInfo(context.workspaceRoot, context.pathEnv);
+	const unavailable = formatUnavailable("git_log", repo);
+	if (unavailable) return {
+		...unavailable,
+		commits: [],
+		truncated: false
+	};
+	if (!repo.hasHead) return {
+		tool: "git_log",
+		path: args.path,
+		content: "This Git repository has no commits yet.",
+		repoRoot: repo.repoRoot,
+		commits: [],
+		truncated: false,
+		warning: "Git repository has no commits."
+	};
+	const repoRoot = requireRepoRoot(repo);
+	const path = args.path ? ensureInsideWorkspace(context.workspaceRoot, args.path).relativePath : void 0;
+	const result = await runGit({
+		cwd: repoRoot,
+		pathEnv: context.pathEnv,
+		args: [
+			"log",
+			"-n",
+			String(args.limit),
+			`--pretty=format:${gitLogPrettyFormat()}`,
+			"--",
+			...path ? [path] : []
+		]
+	});
+	const commits = parseGitLog(result.stdout);
+	return {
+		tool: "git_log",
+		path,
+		content: commits.length === 0 ? "No commits matched." : commits.map(formatCommitSummary).join("\n"),
+		repoRoot: repo.repoRoot,
+		commits,
+		truncated: result.truncated,
+		warning: result.truncated ? "git_log output was truncated." : void 0
+	};
+}
+async function stageGitPaths(context, args) {
+	const repo = await requireAvailableRepo(context);
+	const repoRoot = requireRepoRoot(repo);
+	const paths = normalizeExplicitPaths(context.workspaceRoot, args.paths);
+	const expected = new Map(args.expected_status.map((entry) => [entry.path, entry.status]));
+	const status = await currentStatus(repoRoot, context, true);
+	const statusByPath = new Map(status.map((file) => [file.path, file]));
+	for (const path of paths) {
+		const file = statusByPath.get(path);
+		const expectedStatus = expected.get(path);
+		if (!expectedStatus) throw new Error(`git_add expected_status is required for ${path}.`);
+		if (!file) throw new Error(`git_add can only stage paths present in git_status: ${path}`);
+		if (file.status !== expectedStatus) throw new Error(`git_add expected ${path} to be ${expectedStatus}, but it is ${file.status}.`);
+	}
+	const result = await runGit({
+		cwd: repoRoot,
+		pathEnv: context.pathEnv,
+		args: [
+			"add",
+			"--",
+			...paths
+		]
+	});
+	if (result.exitCode !== 0) throw new Error(`git_add failed: ${result.stderr || result.stdout}`.trim());
+	const files = await currentStatus(repoRoot, context, true);
+	const stagedPaths = files.filter((file) => file.staged).map((file) => file.path);
+	return {
+		tool: "git_add",
+		content: [
+			`staged_paths: ${paths.join(", ")}`,
+			"",
+			formatGitStatusFileList(files)
+		].join("\n").trimEnd(),
+		repoRoot: repo.repoRoot,
+		stagedPaths: paths,
+		files,
+		warning: paths.every((path) => stagedPaths.includes(path)) ? void 0 : "Some requested paths were not staged."
+	};
+}
+async function commitGitPaths(context, args) {
+	const repo = await requireAvailableRepo(context);
+	const repoRoot = requireRepoRoot(repo);
+	const expectedPaths = normalizeExplicitPaths(context.workspaceRoot, args.expected_staged_paths);
+	const stagedFiles = (await currentStatus(repoRoot, context, true)).filter((file) => file.staged);
+	const stagedPaths = stagedFiles.map((file) => file.path).sort();
+	if (stagedPaths.length === 0) throw new Error("git_commit requires staged changes.");
+	if (!sameStringSet(stagedPaths, [...expectedPaths].sort())) throw new Error(`git_commit staged paths did not match expected_staged_paths. staged=${stagedPaths.join(", ")} expected=${expectedPaths.join(", ")}`);
+	const stagedWithUnstagedChanges = stagedFiles.filter((file) => file.unstaged).map((file) => file.path);
+	if (stagedWithUnstagedChanges.length > 0) throw new Error(`git_commit refuses paths with both staged and unstaged changes: ${stagedWithUnstagedChanges.join(", ")}`);
+	const stat = await runGit({
+		cwd: repoRoot,
+		pathEnv: context.pathEnv,
+		args: [
+			"diff",
+			"--cached",
+			"--stat",
+			"--"
+		]
+	});
+	const nameStatus = await runGit({
+		cwd: repoRoot,
+		pathEnv: context.pathEnv,
+		args: [
+			"diff",
+			"--cached",
+			"--name-status",
+			"--"
+		]
+	});
+	const commit = await runGit({
+		cwd: repoRoot,
+		pathEnv: context.pathEnv,
+		args: [
+			"commit",
+			"--no-gpg-sign",
+			"-m",
+			args.message
+		],
+		timeoutMs: 3e4
+	});
+	if (commit.exitCode !== 0) throw new Error(`git_commit failed: ${commit.stderr || commit.stdout}`.trim());
+	const commitSummary = parseGitLog((await runGit({
+		cwd: repoRoot,
+		pathEnv: context.pathEnv,
+		args: [
+			"log",
+			"-n",
+			"1",
+			`--pretty=format:${gitLogPrettyFormat()}`
+		]
+	})).stdout)[0];
+	if (!commitSummary) throw new Error("git_commit succeeded but the new commit could not be read.");
+	const remainingFiles = await currentStatus(repoRoot, context, true);
+	return {
+		tool: "git_commit",
+		content: [
+			`commit: ${commitSummary.shortSha} ${commitSummary.subject}`,
+			`staged_paths: ${stagedPaths.join(", ")}`,
+			"",
+			"stat:",
+			stat.stdout.trim() || "(none)",
+			"",
+			"remaining:",
+			formatGitStatusFileList(remainingFiles) || "clean"
+		].join("\n"),
+		repoRoot: repo.repoRoot,
+		commit: commitSummary,
+		stagedPaths,
+		remainingFiles,
+		stat: stat.stdout,
+		nameStatus: nameStatus.stdout
+	};
+}
+async function requireAvailableRepo(context) {
+	const repo = await getRepoInfo(context.workspaceRoot, context.pathEnv);
+	if (!repo.available) throw new Error(repo.message ?? "Git repository is unavailable.");
+	return repo;
+}
+async function currentStatus(repoRoot, context, includeUntracked) {
+	return parsePorcelainStatus((await runGit({
+		cwd: repoRoot,
+		pathEnv: context.pathEnv,
+		allowNulOutput: true,
+		args: [
+			"status",
+			"--porcelain=v1",
+			"-z",
+			"--no-renames",
+			includeUntracked ? "--untracked-files=all" : "--untracked-files=no",
+			"--"
+		]
+	})).stdout);
+}
+async function runDiff(repoRoot, baseArgs, options) {
+	const result = await runGit({
+		cwd: repoRoot,
+		pathEnv: options.context.pathEnv,
+		args: [
+			...baseArgs,
+			`--unified=${options.contextLines}`,
+			"--",
+			...options.extraPathspecs ?? (options.path ? [options.path] : [])
+		],
+		maxOutputBytes: options.maxBytes,
+		allowExitCodeOne: true
+	});
+	if (result.binary) return {
+		content: "Binary diff omitted.",
+		truncated: result.truncated
+	};
+	return {
+		content: result.stdout,
+		truncated: result.truncated
+	};
+}
+async function diffNameOnly(repoRoot, staged, context, path) {
+	return (await runGit({
+		cwd: repoRoot,
+		pathEnv: context.pathEnv,
+		args: [
+			"diff",
+			staged ? "--cached" : "--no-ext-diff",
+			"--name-only",
+			"--",
+			...path ? [path] : []
+		]
+	})).stdout.split("\n").filter(Boolean);
+}
+async function getUntrackedFiles(repoRoot, context, path) {
+	return (await runGit({
+		cwd: repoRoot,
+		pathEnv: context.pathEnv,
+		args: [
+			"ls-files",
+			"--others",
+			"--exclude-standard",
+			"--",
+			...path ? [path] : []
+		]
+	})).stdout.split("\n").filter(Boolean);
+}
+function appendSection(sections, label, content) {
+	if (content.trim().length === 0) return;
+	sections.push(`## ${label}\n${content.trimEnd()}\n`);
+}
+function formatUnavailable(tool, repo) {
+	if (repo.available) return;
+	return {
+		tool,
+		repoRoot: null,
+		content: repo.message ?? "Git repository is unavailable.",
+		warning: repo.message
+	};
+}
+function formatGitStatusContent(repo, files) {
+	return [
+		`branch: ${repo.branch ?? "(detached)"}`,
+		`head: ${repo.head ?? "(none)"}`,
+		`clean: ${files.length === 0}`,
+		"",
+		formatGitStatusFileList(files) || "No changed files."
+	].join("\n");
+}
+function formatGitStatusFileList(files) {
+	return files.map((file) => `${file.indexStatus}${file.worktreeStatus} ${file.path}`).sort((left, right) => left.localeCompare(right)).join("\n");
+}
+function formatCommitSummary(commit) {
+	return `${commit.shortSha} ${commit.subject} (${commit.authorName}, ${(/* @__PURE__ */ new Date(commit.timestamp * 1e3)).toISOString()})`;
+}
+function requireRepoRoot(repo) {
+	if (!repo.repoRootAbsolute) throw new Error("Git repository root is unavailable.");
+	return repo.repoRootAbsolute;
+}
+function normalizeExplicitPaths(workspaceRoot, paths) {
+	const normalized = paths.map((path) => {
+		if (path === "." || path.includes("*") || path.includes("?") || path.includes("[") || path.includes("]")) throw new Error(`Git mutation tools require explicit file paths, not broad pathspecs: ${path}`);
+		const scoped = ensureInsideWorkspace(workspaceRoot, path);
+		if (scoped.relativePath === ".") throw new Error("Git mutation tools require explicit file paths.");
+		return scoped.relativePath;
+	});
+	return [...new Set(normalized)];
+}
+function sameStringSet(left, right) {
+	return left.length === right.length && left.every((value, index) => value === right[index]);
+}
 const grepTool = defineTool({
 	name: "grep",
 	description: "Search text inside the workspace.",
@@ -632,7 +1352,7 @@ const grepTool = defineTool({
 	})
 });
 async function grepWorkspace(workspaceRoot, args, options = {}) {
-	const scopedPath = resolveWorkspaceScopedPath$1(workspaceRoot, args.path ?? ".");
+	const scopedPath = resolveWorkspaceScopedPath$2(workspaceRoot, args.path ?? ".");
 	const executable = await findSearchExecutable(options.pathEnv);
 	if (!executable) {
 		const warning = "grep could not run because neither rg nor grep is available on PATH.";
@@ -696,7 +1416,7 @@ async function grepWorkspace(workspaceRoot, args, options = {}) {
 		content: truncateToolOutput(result.stdout.trimEnd() || "No matches.")
 	};
 }
-function resolveWorkspaceScopedPath$1(workspaceRoot, path) {
+function resolveWorkspaceScopedPath$2(workspaceRoot, path) {
 	const resolvedWorkspace = resolve(workspaceRoot);
 	const resolvedPath = isAbsolute(path) ? resolve(path) : resolve(resolvedWorkspace, path);
 	const relativePath = relative(resolvedWorkspace, resolvedPath);
@@ -927,6 +1647,8 @@ const READ_ONLY_COMMANDS = new Set([
 	"find",
 	"fd",
 	"cat",
+	"sed",
+	"sort",
 	"head",
 	"tail",
 	"wc",
@@ -1134,6 +1856,7 @@ function validateSimpleCommand(command, context) {
 		case "git": return validateGitCommand(command, context);
 		case "find": return validateFindCommand(command, context);
 		case "fd": return validateGenericCommandArgs(command, context, FD_OPTIONS_WITH_VALUES);
+		case "sed": return validateSedCommand(command, context);
 		default: return validateGenericCommandArgs(command, context, COMMON_OPTIONS_WITH_VALUES);
 	}
 }
@@ -1156,6 +1879,88 @@ function validateGitCommand(command, context) {
 function validateFindCommand(command, context) {
 	return validateGenericCommandArgs(command, context, FIND_OPTIONS_WITH_VALUES);
 }
+function validateSedCommand(command, context) {
+	let sawScript = false;
+	for (let index = 0; index < command.args.length; index += 1) {
+		const arg = command.args[index] ?? "";
+		if (arg === "-i" || arg.startsWith("-i") || arg === "--in-place" || arg.startsWith("--in-place=")) return {
+			allowed: false,
+			reason: "inspect_command rejected 'sed' because in-place edits are unsafe."
+		};
+		if (arg === "-e" || arg === "--expression") {
+			const script = command.args[index + 1];
+			if (!script) return {
+				allowed: false,
+				reason: "inspect_command rejected 'sed' because -e requires a script."
+			};
+			const scriptResult = validateSedScript(script);
+			if (!scriptResult.allowed) return scriptResult;
+			sawScript = true;
+			index += 1;
+			continue;
+		}
+		if (arg === "-n" || arg === "--quiet" || arg === "--silent" || /^-[Erun]+$/.test(arg)) continue;
+		if (arg.startsWith("-")) return {
+			allowed: false,
+			reason: `inspect_command rejected 'sed' because '${arg}' is not allowed.`
+		};
+		if (!sawScript && looksLikeSedScript(arg)) {
+			const scriptResult = validateSedScript(arg);
+			if (!scriptResult.allowed) return scriptResult;
+			sawScript = true;
+			continue;
+		}
+		const scoped = resolveWorkspacePath$1(context.workspaceRoot, arg, context.cwd);
+		if (!scoped.allowed) return {
+			allowed: false,
+			reason: scoped.reason
+		};
+	}
+	return sawScript ? { allowed: true } : {
+		allowed: false,
+		reason: "inspect_command rejected 'sed' because it requires an inline script."
+	};
+}
+function looksLikeSedScript(arg) {
+	return arg.startsWith("s") || /^(\d+|\$)?(,(\d+|\$))?[pdq]$/.test(arg);
+}
+function validateSedScript(script) {
+	if (script.includes("\n")) return {
+		allowed: false,
+		reason: "inspect_command rejected 'sed' because multiline scripts are unsafe."
+	};
+	if (/^(\d+|\$)?(,(\d+|\$))?[pdq]$/.test(script)) return { allowed: true };
+	if (!script.startsWith("s") || script.length < 4) return {
+		allowed: false,
+		reason: "inspect_command rejected 'sed' because only simple read-only scripts are allowed."
+	};
+	const delimiter = script[1] ?? "";
+	if (!delimiter || /[A-Za-z0-9\\\n]/.test(delimiter)) return {
+		allowed: false,
+		reason: "inspect_command rejected 'sed' because the substitution delimiter is invalid."
+	};
+	const delimiters = findUnescapedDelimiterIndexes(script, delimiter);
+	if (delimiters.length < 3) return {
+		allowed: false,
+		reason: "inspect_command rejected 'sed' because the substitution script is incomplete."
+	};
+	const flags = script.slice(delimiters[2] + 1);
+	if (/[^gIpM0-9]/.test(flags) || /[ew]/.test(flags)) return {
+		allowed: false,
+		reason: "inspect_command rejected 'sed' because substitution flags are unsafe."
+	};
+	return { allowed: true };
+}
+function findUnescapedDelimiterIndexes(script, delimiter) {
+	const indexes = [];
+	for (let index = 0; index < script.length; index += 1) {
+		if (script[index] !== delimiter) continue;
+		let slashCount = 0;
+		for (let back = index - 1; back >= 0 && script[back] === "\\"; back -= 1) slashCount += 1;
+		if (slashCount % 2 === 0) indexes.push(index);
+	}
+	return indexes;
+}
 function validateGenericCommandArgs(command, context, optionsWithValues, knownPathlessWords = /* @__PURE__ */ new Set()) {
 	for (let index = 0; index < command.args.length; index += 1) {
 		const arg = command.args[index] ?? "";
@@ -1518,7 +2323,7 @@ const listFilesTool = defineTool({
 	execute: (context, args) => listWorkspaceFiles(context.workspaceRoot, args)
 });
 async function listWorkspaceFiles(workspaceRoot, args) {
-	const scopedPath = resolveWorkspaceScopedPath(workspaceRoot, args.path);
+	const scopedPath = resolveWorkspaceScopedPath$1(workspaceRoot, args.path);
 	if (!(await stat(scopedPath.path)).isDirectory()) throw new Error(`list_files can only list directories inside the workspace: ${args.path}`);
 	const entries = args.recursive ? await collectRecursiveEntries(scopedPath.workspaceRoot, scopedPath.path, args.limit) : await collectTopLevelEntries(scopedPath.workspaceRoot, scopedPath.path, args.limit);
 	const truncated = entries.truncated;
@@ -1582,7 +2387,7 @@ async function sortedDirectoryEntries(path) {
 function formatEntryPath(path, isDirectory) {
 	return isDirectory ? `${path}/` : path;
 }
-function resolveWorkspaceScopedPath(workspaceRoot, path) {
+function resolveWorkspaceScopedPath$1(workspaceRoot, path) {
 	const resolvedWorkspace = resolve(workspaceRoot);
 	const resolvedPath = isAbsolute(path) ? resolve(path) : resolve(resolvedWorkspace, path);
 	const relativePath = relative(resolvedWorkspace, resolvedPath);
@@ -1593,35 +2398,501 @@ function resolveWorkspaceScopedPath(workspaceRoot, path) {
 		relativePath: relativePath || "."
 	};
 }
-const readFileTool = defineTool({
-	name: "read_file",
-	description: "Read a UTF-8 file inside the workspace.",
-	prompt: "read_file: read a UTF-8 file inside the workspace. To use it, reply with only JSON: {\"tool\":\"read_file\",\"args\":{\"path\":\"package.json\"}}",
-	argsSchema: z.object({ path: z.string() }),
-	execute: (context, args) => readWorkspaceFile(context.workspaceRoot, args.path)
-});
-async function readWorkspaceFile(workspaceRoot, path) {
-	const resolvedWorkspace = resolve(workspaceRoot);
-	const resolvedPath = isAbsolute(path) ? resolve(path) : resolve(resolvedWorkspace, path);
-	const relativePath = relative(resolvedWorkspace, resolvedPath);
-	if (relativePath.startsWith("..") || isAbsolute(relativePath)) throw new Error(`read_file can only read files inside the workspace: ${path}`);
-	const bytes = await readFile(resolvedPath);
-	const content = bytes.toString("utf8");
-	return {
-		tool: "read_file",
-		path: relativePath || ".",
-		content,
+//#endregion
+//#region src/cli/ui.ts
+const colors = {
+	bgSoftGray: "\x1B[48;5;236m",
+	blue: "\x1B[34m",
+	cyan: "\x1B[36m",
+	darkGray: "\x1B[90m",
+	dim: "\x1B[2m",
+	green: "\x1B[32m",
+	orange: "\x1B[38;5;208m",
+	purple: "\x1B[35m",
+	red: "\x1B[31m",
+	reset: "\x1B[0m",
+	resetForeground: "\x1B[39m",
+	yellow: "\x1B[33m"
+};
+const ui = {
+	heading(text) {
+		return color(`Topchester ${text}`, "cyan");
+	},
+	label(text) {
+		return color(text, "dim");
+	},
+	muted(text) {
+		return color(text, "darkGray");
+	},
+	model(text) {
+		return color(text, "blue");
+	},
+	modelInline(text) {
+		if (!shouldUseColor()) return text;
+		return `${colors.blue}${text}${colors.resetForeground}`;
+	},
+	ok(text) {
+		return color(text, "green");
+	},
+	warn(text) {
+		return color(text, "yellow");
+	},
+	error(text) {
+		return color(text, "red");
+	},
+	softBackground(text) {
+		return color(text, "bgSoftGray");
+	},
+	async spinner(text, action) {
+		return withStatusLine(text, action, void 0, 80, false);
+	},
+	async progress(text, action) {
+		let latest = text;
+		return withStatusLine(text, () => action((message) => {
+			latest = message;
+		}), () => latest, 80, true);
+	}
+};
+async function withStatusLine(text, action, getText = () => text, progressEveryMs = 80, emitPlainProgress = false) {
+	if (!shouldUseColor()) {
+		if (!emitPlainProgress) return action();
+		const timer = setInterval(() => {
+			stderr.write(`${getText()}\n`);
+		}, Math.max(progressEveryMs, 5e3));
+		try {
+			return await action();
+		} finally {
+			clearInterval(timer);
+		}
+	}
+	const frames = [
+		"⠋",
+		"⠙",
+		"⠹",
+		"⠸",
+		"⠼",
+		"⠴",
+		"⠦",
+		"⠧",
+		"⠇",
+		"⠏"
+	];
+	let index = 0;
+	stderr.write(`${color(frames[index], "cyan")} ${getText()}`);
+	const timer = setInterval(() => {
+		index = (index + 1) % frames.length;
+		stderr.write(`\r\u001b[2K${color(frames[index], "cyan")} ${getText()}`);
+	}, progressEveryMs);
+	try {
+		return await action();
+	} finally {
+		clearInterval(timer);
+		stderr.write(`\r\u001b[2K`);
+	}
+}
+function color(text, colorName) {
+	if (!shouldUseColor()) return text;
+	return `${colors[colorName]}${text}${colors.reset}`;
+}
+function shouldUseColor() {
+	if (process.env.NO_COLOR) return false;
+	if (process.env.FORCE_COLOR && process.env.FORCE_COLOR !== "0") return true;
+	return stdout.isTTY === true;
+}
+//#endregion
+//#region src/agent/task-plan.ts
+const planTodoStatusSchema = z.enum([
+	"pending",
+	"in_progress",
+	"completed"
+]);
+const taskPlanItemSchema = z.object({
+	text: z.string().trim().min(1, "Plan item text cannot be empty."),
+	status: planTodoStatusSchema
+});
+const planTodoArgsSchema = z.object({ items: z.array(taskPlanItemSchema).max(20, "Plan updates are limited to 20 items.") }).superRefine((args, context) => {
+	const seen = /* @__PURE__ */ new Set();
+	let inProgressCount = 0;
+	let incompleteCount = 0;
+	args.items.forEach((item, index) => {
+		const key = item.text.toLocaleLowerCase("en");
+		if (seen.has(key)) context.addIssue({
+			code: "custom",
+			message: "Plan item text must be unique.",
+			path: [
+				"items",
+				index,
+				"text"
+			]
+		});
+		seen.add(key);
+		if (item.status === "in_progress") inProgressCount += 1;
+		if (item.status !== "completed") incompleteCount += 1;
+	});
+	if (inProgressCount > 1) context.addIssue({
+		code: "custom",
+		message: "At most one plan item can be in_progress.",
+		path: ["items"]
+	});
+	if (args.items.length > 0 && incompleteCount > 0 && inProgressCount === 0) context.addIssue({
+		code: "custom",
+		message: "A non-completed plan must have exactly one in_progress item.",
+		path: ["items"]
+	});
+});
+function createEmptyTaskPlanState(now = /* @__PURE__ */ new Date()) {
+	return {
+		items: [],
+		updatedAt: now.toISOString()
+	};
+}
+function applyTaskPlanUpdate(_previous, args, now = /* @__PURE__ */ new Date()) {
+	return {
+		items: planTodoArgsSchema.parse(args).items.map((item) => ({
+			text: item.text,
+			status: item.status
+		})),
+		updatedAt: now.toISOString()
+	};
+}
+function createTaskPlanController(initialState = createEmptyTaskPlanState(), now = () => /* @__PURE__ */ new Date()) {
+	let state = initialState;
+	return {
+		update(args) {
+			state = applyTaskPlanUpdate(state, args, now());
+			return state;
+		},
+		get() {
+			return state;
+		}
+	};
+}
+function summarizeTaskPlan(state) {
+	const pendingCount = state.items.filter((item) => item.status === "pending").length;
+	const inProgressCount = state.items.filter((item) => item.status === "in_progress").length;
+	const completedCount = state.items.filter((item) => item.status === "completed").length;
+	const currentItem = state.items.find((item) => item.status === "in_progress")?.text;
+	return {
+		pendingCount,
+		inProgressCount,
+		completedCount,
+		...currentItem === void 0 ? {} : { currentItem }
+	};
+}
+function hasOpenTaskPlan(state) {
+	return Boolean(state && state.items.some((item) => item.status !== "completed"));
+}
+function formatTaskPlanForPrompt(state) {
+	const summary = summarizeTaskPlan(state);
+	return [
+		"Plan updated",
+		`pending: ${summary.pendingCount}`,
+		`in_progress: ${summary.inProgressCount}`,
+		`completed: ${summary.completedCount}`,
+		summary.currentItem ? `current: ${summary.currentItem}` : ""
+	].filter(Boolean).join("\n");
+}
+function detectTaskPlanChange(previous, next) {
+	const hadPlan = Boolean(previous && previous.items.length > 0);
+	const hasPlan = Boolean(next && next.items.length > 0);
+	if (!hadPlan && hasPlan) return "created";
+	if (hadPlan && !hasPlan) return "cleared";
+	if (hadPlan && hasPlan) return "updated";
+	return "unchanged";
+}
+function formatTaskPlanNotice(change, state) {
+	if (change === "unchanged") return;
+	if (change === "cleared" || state.items.length === 0) return "todo plan cleared";
+	const summary = summarizeTaskPlan(state);
+	if (summary.inProgressCount === 0 && summary.pendingCount === 0) return "todo plan completed";
+	const prefix = change === "created" ? "todo plan created" : "todo plan updated";
+	return summary.currentItem ? `${prefix}: ${summary.currentItem}` : prefix;
+}
+function formatTaskPlanForTui(state, width, visibleLimit = 6) {
+	if (state.items.length === 0) return [];
+	const itemWidth = Math.max(1, Math.max(12, width) - 6);
+	const visibleItems = state.items.slice(0, visibleLimit);
+	const lines = visibleItems.map((item) => formatTaskPlanTuiLine(item, truncateText(item.text, itemWidth)));
+	const remaining = state.items.length - visibleItems.length;
+	if (remaining > 0) lines.push(ui.muted(`  +${remaining} more`));
+	return lines;
+}
+function formatTaskPlanTuiLine(item, text) {
+	switch (item.status) {
+		case "completed": return `  ${ui.ok("[x]")} ${ui.muted(text)}`;
+		case "in_progress": return `  ${ui.ok("[>]")} ${ui.ok(text)}`;
+		case "pending": return `  ${ui.muted("[ ]")} ${text}`;
+	}
+}
+function truncateText(text, width) {
+	if (text.length <= width) return text;
+	if (width <= 3) return ".".repeat(Math.max(0, width));
+	return `${text.slice(0, width - 3)}...`;
+}
+//#endregion
+//#region src/agent/tools/plan-todo.ts
+const planTodoTool = defineTool({
+	name: "plan_todo",
+	description: "Replace the visible session task plan for multi-step work.",
+	prompt: "plan_todo: replace the visible session task plan for non-trivial multi-step work; keep 2-6 short items, exactly one in_progress item while work remains, and use [] only to clear. To use it, reply with only JSON: {\"tool\":\"plan_todo\",\"args\":{\"items\":[{\"text\":\"Inspect relevant files\",\"status\":\"in_progress\"},{\"text\":\"Implement focused change\",\"status\":\"pending\"}]}}",
+	argsSchema: planTodoArgsSchema,
+	async execute(context, args) {
+		if (!context.taskPlan) throw new Error("plan_todo requires runtime task-plan state.");
+		const plan = context.taskPlan.update(args);
+		const summary = summarizeTaskPlan(plan);
+		return {
+			tool: "plan_todo",
+			content: formatTaskPlanForPrompt(plan),
+			plan,
+			...summary
+		};
+	}
+});
+const readFileTool = defineTool({
+	name: "read_file",
+	description: "Read a UTF-8 file inside the workspace.",
+	prompt: "read_file: read a UTF-8 file inside the workspace. To use it, reply with only JSON: {\"tool\":\"read_file\",\"args\":{\"path\":\"package.json\"}}",
+	argsSchema: z.object({ path: z.string() }),
+	execute: (context, args) => readWorkspaceFile(context.workspaceRoot, args.path)
+});
+async function readWorkspaceFile(workspaceRoot, path) {
+	const resolvedWorkspace = resolve(workspaceRoot);
+	const resolvedPath = isAbsolute(path) ? resolve(path) : resolve(resolvedWorkspace, path);
+	const relativePath = relative(resolvedWorkspace, resolvedPath);
+	if (relativePath.startsWith("..") || isAbsolute(relativePath)) throw new Error(`read_file can only read files inside the workspace: ${path}`);
+	const bytes = await readFile(resolvedPath);
+	const content = bytes.toString("utf8");
+	return {
+		tool: "read_file",
+		path: relativePath || ".",
+		content,
 		hash: `sha256:${createHash("sha256").update(bytes).digest("hex")}`
 	};
 }
+const writeFileTool = defineTool({
+	name: "write_file",
+	description: "Create a new UTF-8 file inside the workspace, or explicitly replace one. For overwrite:true, expected_current_hash must be the current/pre-write hash from read_file, never a predicted post-write hash.",
+	prompt: "write_file: create a new UTF-8 file inside the workspace by default; use edit_file for targeted changes to existing files; pass create_parent_dirs:true only when creating the folder path is intended. Replace an existing whole file only with overwrite:true and expected_current_hash set to the current/pre-write hash returned by the latest read_file for that file; never invent it or use a predicted after-write hash. To create a file, reply with only JSON: {\"tool\":\"write_file\",\"args\":{\"path\":\"test/example.test.ts\",\"content\":\"import { it, expect } from \\\"vitest\\\";\\n\\nit(\\\"works\\\", () => {\\n  expect(true).toBe(true);\\n});\\n\",\"create_parent_dirs\":true}}",
+	argsSchema: z.object({
+		path: z.string().describe("Workspace-relative path to write."),
+		content: z.string().describe("Complete UTF-8 file content to write."),
+		create_parent_dirs: z.boolean().optional().describe("Create missing parent directories only when that is explicitly intended."),
+		overwrite: z.boolean().optional().describe("Set true only for intentional whole-file replacement."),
+		expected_current_hash: z.string().optional().describe("Required with overwrite:true. Use the current file hash returned by the latest read_file result for this file. This is checked before writing and is not the hash after the write.")
+	}),
+	execute: (context, args) => writeWorkspaceFile(context.workspaceRoot, args, { logger: context.logger })
+});
+async function writeWorkspaceFile(workspaceRoot, args, options = {}) {
+	const scopedPath = resolveWorkspaceScopedPath(workspaceRoot, args.path);
+	return enqueueFileMutation(scopedPath.path, async () => {
+		const existingTarget = await statTarget(scopedPath.path);
+		if (args.overwrite) return overwriteExistingFile(workspaceRoot, scopedPath, args, existingTarget, options);
+		if (existingTarget) throw new Error(`write_file can only create new files: ${scopedPath.relativePath}`);
+		const createdParentDirs = await ensureParentDirectory(scopedPath.workspaceRoot, scopedPath.path, scopedPath.relativePath, Boolean(args.create_parent_dirs));
+		const bytes = encodeUtf8Text(args.content);
+		const hash = hashBytes(bytes);
+		const lineCount = countLogicalLines$1(args.content);
+		await writeFileAtomically(scopedPath.path, bytes);
+		const writeEvent = {
+			kind: "file_create",
+			source: "agent",
+			path: scopedPath.relativePath,
+			afterHash: hash,
+			firstChangedLine: 1,
+			writeSummary: `created +${lineCount}`,
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		const overlayState = recordAgentFileCreate(workspaceRoot, writeEvent);
+		options.logger?.debug({
+			event: "file_create",
+			...writeEvent,
+			bytesWritten: bytes.length,
+			lineCount,
+			createdParentDirs,
+			kbState: overlayState.kbState,
+			dirtyFileCount: overlayState.dirtyFiles.length
+		}, "file create");
+		const content = [
+			`Created ${scopedPath.relativePath}`,
+			`hash: ${hash}`,
+			`bytes_written: ${bytes.length}`,
+			`line_count: ${lineCount}`,
+			`kb_state: ${overlayState.kbState}`,
+			createdParentDirs.length > 0 ? `created_parent_dirs: ${createdParentDirs.join(", ")}` : void 0
+		].filter(Boolean).join("\n");
+		return {
+			tool: "write_file",
+			path: scopedPath.relativePath,
+			content,
+			hash,
+			bytesWritten: bytes.length,
+			lineCount,
+			createdParentDirs,
+			kbState: "needs_sync",
+			writeEvent
+		};
+	});
+}
+async function overwriteExistingFile(workspaceRoot, scopedPath, args, existingTarget, options) {
+	if (!args.expected_current_hash) throw new Error(`write_file overwrite requires expected_current_hash for ${scopedPath.relativePath}.`);
+	if (!existingTarget) throw new Error(`write_file overwrite requires an existing file: ${scopedPath.relativePath}`);
+	if (!existingTarget.isFile()) throw new Error(`write_file overwrite requires a regular file: ${scopedPath.relativePath}`);
+	const beforeBytes = await readFile(scopedPath.path);
+	const beforeHash = hashBytes(beforeBytes);
+	if (args.expected_current_hash !== beforeHash) throw new Error(`write_file expected_current_hash did not match ${scopedPath.relativePath}.`);
+	const beforeLineCount = countLogicalLines$1(decodeUtf8(scopedPath.relativePath, beforeBytes));
+	const afterBytes = encodeUtf8Text(args.content);
+	const afterHash = hashBytes(afterBytes);
+	const afterLineCount = countLogicalLines$1(args.content);
+	const bytesChanged = afterBytes.length - beforeBytes.length;
+	const lineDelta = afterLineCount - beforeLineCount;
+	await writeFileAtomically(scopedPath.path, afterBytes, Number(existingTarget.mode));
+	const writeEvent = {
+		kind: "file_overwrite",
+		source: "agent",
+		path: scopedPath.relativePath,
+		beforeHash,
+		afterHash,
+		firstChangedLine: 1,
+		writeSummary: `overwritten +${afterLineCount}/-${beforeLineCount}`,
+		timestamp: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	const overlayState = recordAgentFileMutation(workspaceRoot, writeEvent);
+	options.logger?.debug({
+		event: "file_overwrite",
+		...writeEvent,
+		bytesWritten: afterBytes.length,
+		bytesChanged,
+		lineCount: afterLineCount,
+		lineDelta,
+		kbState: overlayState.kbState,
+		dirtyFileCount: overlayState.dirtyFiles.length
+	}, "file overwrite");
+	const content = [
+		`Overwrote ${scopedPath.relativePath}`,
+		`before_hash: ${beforeHash}`,
+		`after_hash: ${afterHash}`,
+		`bytes_written: ${afterBytes.length}`,
+		`bytes_changed: ${bytesChanged}`,
+		`line_count: ${afterLineCount}`,
+		`line_delta: ${lineDelta}`,
+		`kb_state: ${overlayState.kbState}`
+	].join("\n");
+	return {
+		tool: "write_file",
+		path: scopedPath.relativePath,
+		content,
+		hash: afterHash,
+		beforeHash,
+		bytesWritten: afterBytes.length,
+		bytesChanged,
+		lineCount: afterLineCount,
+		lineDelta,
+		createdParentDirs: [],
+		kbState: "needs_sync",
+		writeEvent
+	};
+}
+function resolveWorkspaceScopedPath(workspaceRoot, path) {
+	if (path.includes("\0") || path.length === 0) throw new Error("write_file path is invalid.");
+	const resolvedWorkspace = resolve(workspaceRoot);
+	const resolvedPath = isAbsolute(path) ? resolve(path) : resolve(resolvedWorkspace, path);
+	const relativePath = relative(resolvedWorkspace, resolvedPath);
+	if (relativePath.startsWith("..") || isAbsolute(relativePath)) throw new Error(`write_file can only write files inside the workspace: ${path}`);
+	if (relativePath === "") throw new Error("write_file path must point to a file inside the workspace.");
+	return {
+		workspaceRoot: resolvedWorkspace,
+		path: resolvedPath,
+		relativePath
+	};
+}
+async function statTarget(path) {
+	try {
+		return await stat(path);
+	} catch (error) {
+		if (isNodeError$2(error) && error.code === "ENOENT") return;
+		throw error;
+	}
+}
+async function ensureParentDirectory(workspaceRoot, path, relativePath, createParentDirs) {
+	const parent = dirname(path);
+	try {
+		if (!(await stat(parent)).isDirectory()) throw new Error(`write_file parent path is not a directory: ${dirname(relativePath)}`);
+		return [];
+	} catch (error) {
+		if (!isNodeError$2(error) || error.code !== "ENOENT") throw error;
+	}
+	if (!createParentDirs) throw new Error(`write_file parent directory does not exist: ${dirname(relativePath)}`);
+	const createdParentDirs = await collectMissingParentDirs(workspaceRoot, parent);
+	await mkdir(parent, { recursive: true });
+	return createdParentDirs;
+}
+async function collectMissingParentDirs(workspaceRoot, parent) {
+	const missing = [];
+	let current = parent;
+	while (current !== workspaceRoot) try {
+		if (!(await stat(current)).isDirectory()) throw new Error(`write_file parent path is not a directory: ${relative(workspaceRoot, current)}`);
+		break;
+	} catch (error) {
+		if (!isNodeError$2(error) || error.code !== "ENOENT") throw error;
+		missing.push(relative(workspaceRoot, current));
+		current = dirname(current);
+	}
+	return missing.reverse();
+}
+function encodeUtf8Text(content) {
+	if (content.includes("\0")) throw new Error("write_file content must not contain NUL bytes.");
+	return Buffer.from(content, "utf8");
+}
+function decodeUtf8(path, bytes) {
+	try {
+		return new TextDecoder("utf-8", {
+			fatal: true,
+			ignoreBOM: true
+		}).decode(bytes);
+	} catch {
+		throw new Error(`write_file overwrite requires the existing file to be UTF-8 text: ${path}`);
+	}
+}
+async function writeFileAtomically(path, content, mode = 438) {
+	const temporaryPath = resolve(dirname(path), `.${basename(path)}.topchester-${process.pid}-${randomUUID()}.tmp`);
+	try {
+		await writeFile(temporaryPath, content, {
+			flag: "wx",
+			mode: mode & 511
+		});
+		await rename(temporaryPath, path);
+	} catch (error) {
+		await rm(temporaryPath, { force: true });
+		throw error;
+	}
+}
+function hashBytes(bytes) {
+	return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+function countLogicalLines$1(content) {
+	if (content.length === 0) return 0;
+	const withoutTrailingLineEnding = content.replace(/\r?\n$/u, "");
+	return withoutTrailingLineEnding.length === 0 ? 1 : withoutTrailingLineEnding.split(/\r?\n/u).length;
+}
+function isNodeError$2(error) {
+	return error instanceof Error && "code" in error;
+}
 //#endregion
 //#region src/agent/tools/registry.ts
 const toolRegistry = {
+	[planTodoTool.name]: planTodoTool,
 	[readFileTool.name]: readFileTool,
 	[listFilesTool.name]: listFilesTool,
 	[grepTool.name]: grepTool,
 	[findFileTool.name]: findFileTool,
 	[editFileTool.name]: editFileTool,
+	[writeFileTool.name]: writeFileTool,
+	[gitStatusTool.name]: gitStatusTool,
+	[gitDiffTool.name]: gitDiffTool,
+	[gitLogTool.name]: gitLogTool,
+	[gitAddTool.name]: gitAddTool,
+	[gitCommitTool.name]: gitCommitTool,
 	[inspectCommandTool.name]: inspectCommandTool
 };
 function isToolName(name) {
@@ -1837,16 +3108,23 @@ var ModelGateway = class ModelGateway {
 	}
 	async generateText(request) {
 		const resolved = this.resolveModel(request.purpose);
+		const result = await generateText({
+			model: resolved.model,
+			system: request.system,
+			prompt: request.prompt,
+			abortSignal: request.abortSignal
+		});
+		const usage = normalizeUsage(result.usage, {
+			providerId: resolved.providerId,
+			providerConfig: resolved.providerConfig,
+			responseBody: result.response.body
+		});
 		return {
-			text: (await generateText({
-				model: resolved.model,
-				system: request.system,
-				prompt: request.prompt,
-				abortSignal: request.abortSignal
-			})).text,
+			text: result.text,
 			providerId: resolved.providerId,
 			modelId: resolved.modelId,
-			purpose: resolved.purpose
+			purpose: resolved.purpose,
+			...usage ? { usage } : {}
 		};
 	}
 	async generateAgentStep(request) {
@@ -1879,7 +3157,7 @@ var ModelGateway = class ModelGateway {
 			}
 			return result;
 		} catch (error) {
-			const reason = formatErrorMessage$1(error);
+			const reason = formatErrorMessage$2(error);
 			attempts.push({
 				protocol: "native-openai-compatible",
 				status: "failed",
@@ -1915,6 +3193,11 @@ var ModelGateway = class ModelGateway {
 			providerOptions,
 			abortSignal: request.abortSignal
 		});
+		const usage = normalizeUsage(result.usage, {
+			providerId: resolved.providerId,
+			providerConfig: resolved.providerConfig,
+			responseBody: result.response.body
+		});
 		const toolCalls = result.toolCalls.map((call, index) => {
 			const parsed = parseNativeToolCall(call.toolName, call.input);
 			if (!parsed) throw new Error(`Native tool call for ${call.toolName} did not match the registered schema.`);
@@ -1934,6 +3217,7 @@ var ModelGateway = class ModelGateway {
 			providerId: resolved.providerId,
 			modelId: resolved.modelId,
 			purpose: resolved.purpose,
+			...usage ? { usage } : {},
 			toolCalls,
 			toolProtocol: "native-openai-compatible",
 			protocolAttempts: attempts,
@@ -1949,6 +3233,11 @@ var ModelGateway = class ModelGateway {
 			prompt: request.prompt,
 			abortSignal: request.abortSignal
 		});
+		const usage = normalizeUsage(result.usage, {
+			providerId: resolved.providerId,
+			providerConfig: resolved.providerConfig,
+			responseBody: result.response.body
+		});
 		const parsed = parseToolCallWithSource(result.text, allowedSources);
 		const defaultProtocol = allowedSources.length === 1 && allowedSources[0] === "text-xml" ? "text-xml" : "text-json";
 		const toolProtocol = parsed?.source === "text-xml" ? "text-xml" : parsed ? "text-json" : defaultProtocol;
@@ -1962,6 +3251,7 @@ var ModelGateway = class ModelGateway {
 			providerId: resolved.providerId,
 			modelId: resolved.modelId,
 			purpose: resolved.purpose,
+			...usage ? { usage } : {},
 			toolCalls: parsed ? [{
 				id: `${parsed.source}-0`,
 				tool: parsed.call.tool,
@@ -1990,6 +3280,9 @@ function buildNativeProviderOptions(providerId, config) {
 function shouldApplyOpenRouterRoutingOptions(providerId, config) {
 	if (config.openRouterToolRouting === "force") return true;
 	if (config.openRouterToolRouting === "off") return false;
+	return isOpenRouterProvider(providerId, config);
+}
+function isOpenRouterProvider(providerId, config) {
 	return providerId.toLowerCase().includes("openrouter") || config.baseURL.toLowerCase().includes("openrouter.ai");
 }
 function hasOpenRouterRoutingOptions(providerOptions, providerId) {
@@ -1997,14 +3290,32 @@ function hasOpenRouterRoutingOptions(providerOptions, providerId) {
 	return Boolean(options && typeof options === "object" && "provider" in options);
 }
 function isNativeToolFallbackError(error) {
-	const message = formatErrorMessage$1(error).toLowerCase();
+	const message = formatErrorMessage$2(error).toLowerCase();
 	return message.includes("tool") || message.includes("function") || message.includes("parallel_tool_calls") || message.includes("tool_choice") || message.includes("requested parameters") || message.includes("provider routing") || message.includes("provider-selection") || message.includes("invalid request");
 }
 function extractWarningMessages(warnings) {
 	if (!Array.isArray(warnings)) return [];
-	return warnings.map((warning) => formatErrorMessage$1(warning));
+	return warnings.map((warning) => formatErrorMessage$2(warning));
+}
+function normalizeUsage(usage, context) {
+	const costUsd = context && isOpenRouterProvider(context.providerId, context.providerConfig) ? extractOpenRouterCost(context.responseBody) : void 0;
+	if (!usage) return costUsd === void 0 ? void 0 : { costUsd };
+	const normalized = {
+		...typeof usage.inputTokens === "number" ? { inputTokens: usage.inputTokens } : {},
+		...typeof usage.outputTokens === "number" ? { outputTokens: usage.outputTokens } : {},
+		...typeof usage.totalTokens === "number" ? { totalTokens: usage.totalTokens } : {},
+		...costUsd === void 0 ? {} : { costUsd }
+	};
+	return Object.keys(normalized).length > 0 ? normalized : void 0;
 }
-function formatErrorMessage$1(error) {
+function extractOpenRouterCost(responseBody) {
+	if (!responseBody || typeof responseBody !== "object") return;
+	const usage = responseBody.usage;
+	if (!usage || typeof usage !== "object") return;
+	const cost = usage.cost;
+	return typeof cost === "number" && Number.isFinite(cost) ? cost : void 0;
+}
+function formatErrorMessage$2(error) {
 	return error instanceof Error ? error.message : String(error);
 }
 //#endregion
@@ -2014,8 +3325,6 @@ const modelPurposeSchema = z.enum([
 	"agent.fast",
 	"kb.scan",
 	"kb.summarize",
-	"kb.extract",
-	"kb.embed",
 	"fallback"
 ]);
 const modelPurposes = modelPurposeSchema.options;
@@ -2110,7 +3419,7 @@ function readConfigFile(path) {
 	try {
 		return parse(readFileSync(path, "utf8"));
 	} catch (error) {
-		throw new Error(`Invalid Topchester config at ${path}: ${formatErrorMessage(error)}`);
+		throw new Error(`Invalid Topchester config at ${path}: ${formatErrorMessage$1(error)}`);
 	}
 }
 function parseConfigFile(path, value) {
@@ -2146,6 +3455,7 @@ function normalizeConfigInput(value) {
 		ensureKnownProvider(providers, kbSummarizeModelRef.provider);
 		delete models["kb.summarize"];
 	}
+	applyKnownProviderDefaults(providers);
 	return {
 		...value,
 		models: {
@@ -2202,6 +3512,20 @@ function ensureKnownProvider(providers, provider) {
 		}
 	};
 }
+function applyKnownProviderDefaults(providers) {
+	for (const [providerId, provider] of Object.entries(providers)) {
+		if (!isPlainObject(provider) || provider.type !== "openai-compatible" || typeof provider.baseURL !== "string") continue;
+		if (isOpenAIProvider(providerId, provider.baseURL)) {
+			provider.supportsStructuredOutputs ??= true;
+			provider.toolProtocol ??= "native";
+		}
+	}
+}
+function isOpenAIProvider(providerId, baseURL) {
+	const normalizedProvider = providerId.toLowerCase();
+	const normalizedBaseURL = baseURL.toLowerCase();
+	return normalizedProvider === "openai" || normalizedProvider === "gpt" || normalizedProvider.includes("openai") || normalizedBaseURL.includes("api.openai.com");
+}
 function deepMerge(base, override, path = []) {
 	if (Array.isArray(base) && Array.isArray(override)) return path.join(".") === "ignore.paths" ? [...base, ...override] : override;
 	if (!isPlainObject(base) || !isPlainObject(override)) return override;
@@ -2215,7 +3539,7 @@ function isPlainObject(value) {
 function formatZodIssue(issue) {
 	return `${issue.path.length > 0 ? issue.path.join(".") : "<root>"}: ${issue.message}`;
 }
-function formatErrorMessage(error) {
+function formatErrorMessage$1(error) {
 	return error instanceof Error ? error.message : String(error);
 }
 //#endregion
@@ -2309,107 +3633,6 @@ function normalizeModelGatewayConfig(config) {
 	};
 }
 //#endregion
-//#region src/cli/ui.ts
-const colors = {
-	bgSoftGray: "\x1B[48;5;236m",
-	blue: "\x1B[34m",
-	cyan: "\x1B[36m",
-	darkGray: "\x1B[90m",
-	dim: "\x1B[2m",
-	green: "\x1B[32m",
-	orange: "\x1B[38;5;208m",
-	purple: "\x1B[35m",
-	red: "\x1B[31m",
-	reset: "\x1B[0m",
-	resetForeground: "\x1B[39m",
-	yellow: "\x1B[33m"
-};
-const ui = {
-	heading(text) {
-		return color(`Topchester ${text}`, "cyan");
-	},
-	label(text) {
-		return color(text, "dim");
-	},
-	muted(text) {
-		return color(text, "darkGray");
-	},
-	model(text) {
-		return color(text, "blue");
-	},
-	modelInline(text) {
-		if (!shouldUseColor()) return text;
-		return `${colors.blue}${text}${colors.resetForeground}`;
-	},
-	ok(text) {
-		return color(text, "green");
-	},
-	warn(text) {
-		return color(text, "yellow");
-	},
-	error(text) {
-		return color(text, "red");
-	},
-	softBackground(text) {
-		return color(text, "bgSoftGray");
-	},
-	async spinner(text, action) {
-		return withStatusLine(text, action, void 0, 80, false);
-	},
-	async progress(text, action) {
-		let latest = text;
-		return withStatusLine(text, () => action((message) => {
-			latest = message;
-		}), () => latest, 80, true);
-	}
-};
-async function withStatusLine(text, action, getText = () => text, progressEveryMs = 80, emitPlainProgress = false) {
-	if (!shouldUseColor()) {
-		if (!emitPlainProgress) return action();
-		const timer = setInterval(() => {
-			stderr.write(`${getText()}\n`);
-		}, Math.max(progressEveryMs, 5e3));
-		try {
-			return await action();
-		} finally {
-			clearInterval(timer);
-		}
-	}
-	const frames = [
-		"⠋",
-		"⠙",
-		"⠹",
-		"⠸",
-		"⠼",
-		"⠴",
-		"⠦",
-		"⠧",
-		"⠇",
-		"⠏"
-	];
-	let index = 0;
-	stderr.write(`${color(frames[index], "cyan")} ${getText()}`);
-	const timer = setInterval(() => {
-		index = (index + 1) % frames.length;
-		stderr.write(`\r\u001b[2K${color(frames[index], "cyan")} ${getText()}`);
-	}, progressEveryMs);
-	try {
-		return await action();
-	} finally {
-		clearInterval(timer);
-		stderr.write(`\r\u001b[2K`);
-	}
-}
-function color(text, colorName) {
-	if (!shouldUseColor()) return text;
-	return `${colors[colorName]}${text}${colors.reset}`;
-}
-function shouldUseColor() {
-	if (process.env.NO_COLOR) return false;
-	if (process.env.FORCE_COLOR && process.env.FORCE_COLOR !== "0") return true;
-	return stdout.isTTY === true;
-}
-//#endregion
 //#region src/knowledge/status.ts
 function getKnowledgeStatus(workspaceRoot) {
 	const kbPathSource = process.env.TOPCHESTER_KB_DIR ? "env" : "default";
@@ -2742,6 +3965,14 @@ const l1ConfidenceLevels = [
 	"medium",
 	"high"
 ];
+const l1FileRoles = [
+	"source",
+	"test",
+	"config",
+	"doc",
+	"script",
+	"unknown"
+];
 const nonEmptyStringSchema = z.string().min(1);
 const sha256HashSchema = z.string().regex(/^sha256:[a-f0-9]{64}$/);
 const isoUtcTimestampSchema = z.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?Z$/).refine((value) => !Number.isNaN(Date.parse(value)), { message: "Expected a valid UTC ISO timestamp" });
@@ -2753,7 +3984,7 @@ const l1FileSymbolSchema = z.object({
 	kind: nonEmptyStringSchema,
 	name: nonEmptyStringSchema,
 	exported: z.boolean(),
-	summary: nonEmptyStringSchema
+	summary: nonEmptyStringSchema.optional()
 }).strict();
 const l1FileEvidenceSchema = z.object({
 	kind: nonEmptyStringSchema,
@@ -2770,6 +4001,7 @@ const l1FileEntrySchema = z.object({
 	size_bytes: z.number().int().nonnegative(),
 	last_scanned_at: isoUtcTimestampSchema,
 	scan_status: z.enum(l1FileScanStatuses),
+	file_role: z.enum(l1FileRoles).default("unknown"),
 	summary: nonEmptyStringSchema,
 	responsibilities: z.array(nonEmptyStringSchema),
 	symbols: z.array(l1FileSymbolSchema),
@@ -2778,6 +4010,9 @@ const l1FileEntrySchema = z.object({
 	module_ids: z.array(l1ModuleIdSchema),
 	feature_ids: z.array(l1FeatureIdSchema),
 	test_ids: z.array(l1FileIdSchema),
+	declared_test_targets: z.array(l1FileIdSchema).default([]),
+	likely_test_targets: z.array(l1FileIdSchema).default([]),
+	tested_by: z.array(l1FileIdSchema).default([]),
 	evidence: z.array(l1FileEvidenceSchema),
 	confidence: z.enum(l1ConfidenceLevels)
 }).strict().refine((entry) => entry.id === `file:${entry.path}`, {
@@ -2845,6 +4080,123 @@ function formatCountProgress(label, completed, total, detail) {
 	return `${label} [${formatProgressBar(safeCompleted, safeTotal)}] ${safeCompleted}/${safeTotal} (${percent}%)${suffix}`;
 }
 //#endregion
+//#region src/knowledge/compiler/l1-postprocess.ts
+async function postProcessL1Entries(kbPath) {
+	const entries = await loadL1Entries(kbPath);
+	const entriesById = new Map(entries.map(({ entry }) => [entry.id, entry]));
+	const entriesByPath = new Map(entries.map(({ entry }) => [entry.path, entry]));
+	const testTargetsById = /* @__PURE__ */ new Map();
+	for (const { entry } of entries) {
+		if (inferL1FileRole(entry.path) !== "test") {
+			testTargetsById.set(entry.id, {
+				declared: [],
+				likely: []
+			});
+			continue;
+		}
+		const declared = dedupeStrings$1([...entry.declared_test_targets.filter((id) => isExistingNonSelfFileId(id, entry.id, entriesById)), ...entry.imports.filter((id) => isExistingNonSelfFileId(id, entry.id, entriesById))]);
+		const likely = dedupeStrings$1([...entry.likely_test_targets.filter((id) => isExistingNonSelfFileId(id, entry.id, entriesById)), ...inferLikelyTestTargets(entry.path, entriesByPath)]);
+		testTargetsById.set(entry.id, {
+			declared,
+			likely
+		});
+	}
+	const testedBy = /* @__PURE__ */ new Map();
+	for (const [testId, links] of testTargetsById) for (const targetId of dedupeStrings$1([...links.declared, ...links.likely])) {
+		const list = testedBy.get(targetId) ?? [];
+		list.push(testId);
+		testedBy.set(targetId, list);
+	}
+	let entriesUpdated = 0;
+	let testLinksAdded = 0;
+	for (const { entry, entryPath } of entries) {
+		const fileRole = inferL1FileRole(entry.path);
+		const links = testTargetsById.get(entry.id) ?? {
+			declared: [],
+			likely: []
+		};
+		const nextEntry = parseL1FileEntry({
+			...entry,
+			file_role: fileRole,
+			declared_test_targets: links.declared,
+			likely_test_targets: links.likely,
+			tested_by: dedupeStrings$1(testedBy.get(entry.id) ?? []).sort()
+		});
+		testLinksAdded += nextEntry.declared_test_targets.length + nextEntry.likely_test_targets.length + nextEntry.tested_by.length;
+		if (JSON.stringify(nextEntry) !== JSON.stringify(entry)) {
+			await writeFile(entryPath, `${JSON.stringify(nextEntry, null, 2)}\n`);
+			entriesUpdated += 1;
+		}
+	}
+	return {
+		entriesRead: entries.length,
+		entriesUpdated,
+		testLinksAdded
+	};
+}
+function inferL1FileRole(path) {
+	const lowerPath = path.toLowerCase();
+	const name = basename(lowerPath);
+	if (isTestPath(lowerPath)) return "test";
+	if (lowerPath.startsWith("scripts/") || lowerPath.startsWith("script/") || lowerPath.endsWith(".sh")) return "script";
+	if (lowerPath.endsWith(".md") || lowerPath.endsWith(".mdx") || lowerPath.startsWith("docs/")) return "doc";
+	if (name === "package.json" || name.endsWith("lock.json") || name.endsWith("-lock.yaml") || name.endsWith(".config.ts") || name.endsWith(".config.js") || name.endsWith(".config.mjs") || name.endsWith(".config.cjs") || name === "tsconfig.json" || name.startsWith(".")) return "config";
+	if (/\.(ts|tsx|js|jsx|mts|cts)$/.test(lowerPath)) return "source";
+	return "unknown";
+}
+async function loadL1Entries(kbPath) {
+	const entryPaths = await listJsonFiles$1(join(kbPath, "l1-files")).catch((error) => {
+		if (isFileNotFoundError$3(error)) return [];
+		throw error;
+	});
+	const entries = [];
+	for (const entryPath of entryPaths) entries.push({
+		entryPath,
+		entry: parseL1FileEntry(JSON.parse(await readFile(entryPath, "utf8")))
+	});
+	return entries.sort((a, b) => a.entry.path.localeCompare(b.entry.path));
+}
+async function listJsonFiles$1(directory) {
+	const entries = await readdir(directory, { withFileTypes: true });
+	const files = [];
+	for (const entry of entries) {
+		const entryPath = join(directory, entry.name);
+		if (entry.isDirectory()) files.push(...await listJsonFiles$1(entryPath));
+		else if (entry.isFile() && entry.name.endsWith(".json")) files.push(entryPath);
+	}
+	return files.sort();
+}
+function inferLikelyTestTargets(testPath, entriesByPath) {
+	const candidates = /* @__PURE__ */ new Set();
+	const sourceLikePath = removeTestSuffix(testPath);
+	candidates.add(sourceLikePath);
+	for (const prefix of [
+		"test/",
+		"tests/",
+		"__tests__/"
+	]) if (testPath.startsWith(prefix)) candidates.add(`src/${removeTestSuffix(testPath.slice(prefix.length))}`);
+	if (testPath.includes("/__tests__/")) candidates.add(removeTestSuffix(testPath.replace("/__tests__/", "/")));
+	return [...candidates].filter((candidate) => candidate !== testPath).flatMap((candidate) => {
+		const entry = entriesByPath.get(candidate);
+		return entry ? [entry.id] : [];
+	});
+}
+function removeTestSuffix(path) {
+	return path.replace(/\.(test|spec)(\.[^./]+)$/i, "$2");
+}
+function isTestPath(path) {
+	return /\.(test|spec)\.(ts|tsx|js|jsx|mts|cts)$/.test(path) || path.startsWith("test/") || path.startsWith("tests/") || path.startsWith("__tests__/") || path.includes("/__tests__/");
+}
+function isExistingNonSelfFileId(id, selfId, entriesById) {
+	return id !== selfId && entriesById.has(id);
+}
+function dedupeStrings$1(values) {
+	return [...new Set(values)];
+}
+function isFileNotFoundError$3(error) {
+	return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+//#endregion
 //#region src/knowledge/compiler/manifest.ts
 const knowledgeCompilerIdentity = {
 	name: "topchester-knowledge-compiler",
@@ -2887,6 +4239,8 @@ async function processL1Queue(options) {
 		await persistQueue(options.queuePath, queuedFiles, now().toISOString());
 		options.onProgress?.({ message: formatL1ProgressMessage("Processing L1 files", index + 1, queuedFiles.length, item.path) });
 	}
+	options.onProgress?.({ message: "Linking L1 file relationships..." });
+	await postProcessL1Entries(options.kbPath);
 	const summary = await summarizeL1Queue(options.kbPath, queuedFiles);
 	await writeManifest(options, summary, now().toISOString());
 	return {
@@ -2946,7 +4300,11 @@ async function processL1QueueItem(options) {
 }
 function buildL1FileEntrySystemPrompt() {
 	return [
-		"You summarize one repository file for Topchester's L1 knowledge base.",
+		"You create concise, structured repository knowledge for one file.",
+		"Prefer concrete facts visible in the file over generic descriptions.",
+		"Do not invent modules, features, tests, routes, or dependencies.",
+		"If uncertain, leave arrays empty and use lower confidence.",
+		"Avoid filler such as \"This file contains code\" or \"Symbol named X\".",
 		"Return exactly one JSON object and no markdown.",
 		"Do not include secrets, credentials, or raw provider payloads."
 	].join("\n");
@@ -2955,6 +4313,35 @@ function buildL1FileEntryPrompt(input) {
 	return [
 		"Create an L1 file entry for this workspace-relative path.",
 		"The compiler will overwrite id, path, content_hash, size_bytes, last_scanned_at, and scan_status.",
+		"",
+		"Extraction rules:",
+		"- summary: one specific sentence about the file's role in this project.",
+		"- responsibilities: 2-6 concrete responsibilities, no duplicates, no generic boilerplate.",
+		"- symbols: important declared or exported interfaces, types, classes, functions, constants, schemas, commands, routes, React components, tests, or config objects.",
+		"  For each symbol, set:",
+		"  - kind: interface | type | class | function | const | component | schema | command | route | test | config | symbol",
+		"  - name: exact identifier or stable label",
+		"  - exported: true only when exported from this file",
+		"  - summary: include only if it adds useful meaning beyond the name",
+		"- imports: only workspace-local file dependencies as file:<path>; omit packages and built-ins.",
+		"- exports: exact exported names from this file as strings.",
+		"- test_ids: only file:<path> when this file is clearly a test or clearly references a test target.",
+		"- file_role: source | test | config | doc | script | unknown.",
+		"- declared_test_targets: for test files, file:<path> entries that this test directly imports or names.",
+		"- likely_test_targets: for test files, file:<path> entries likely covered by path/name convention.",
+		"- tested_by: leave empty; the compiler fills reverse test links after all files are processed.",
+		"- module_ids and feature_ids: leave empty unless there is strong evidence.",
+		"- evidence: include at least { \"kind\": \"path\", \"value\": \"<path>\" } and any high-signal local evidence.",
+		"- confidence: high for simple files with clear structure, medium for normal files, low for vague/generated/config-heavy files.",
+		"",
+		"Quality rules:",
+		"- Return valid JSON only.",
+		"- Keep arrays concise.",
+		"- Deduplicate all arrays.",
+		"- Prefer exact names from source.",
+		"- Do not copy large code snippets.",
+		"- Do not include secrets or raw credentials.",
+		"",
 		"Use this JSON shape:",
 		JSON.stringify({
 			$schema: l1FileEntrySchemaPath,
@@ -2967,6 +4354,7 @@ function buildL1FileEntryPrompt(input) {
 			size_bytes: 0,
 			last_scanned_at: "2026-05-11T00:00:00Z",
 			scan_status: "current",
+			file_role: "source",
 			summary: "One clear sentence.",
 			responsibilities: ["What this file owns or does."],
 			symbols: [],
@@ -2975,6 +4363,9 @@ function buildL1FileEntryPrompt(input) {
 			module_ids: [],
 			feature_ids: [],
 			test_ids: [],
+			declared_test_targets: [],
+			likely_test_targets: [],
+			tested_by: [],
 			evidence: [{
 				kind: "path",
 				value: "<path>"
@@ -3012,41 +4403,49 @@ function normalizeL1FileEntry(value, deterministic) {
 }
 function normalizeModelOwnedL1Fields(value, path) {
 	const record = value;
+	const exports = normalizeStringArray(record.exports);
 	return {
 		...record,
+		file_role: inferL1FileRole(path),
 		responsibilities: normalizeStringArray(record.responsibilities),
-		symbols: normalizeSymbols(record.symbols, path),
+		symbols: normalizeSymbols(record.symbols, path, exports),
 		imports: normalizePrefixedIds(record.imports, "file:"),
-		exports: normalizeStringArray(record.exports),
+		exports,
 		module_ids: normalizePrefixedIds(record.module_ids, "module:"),
 		feature_ids: normalizePrefixedIds(record.feature_ids, "feature:"),
 		test_ids: normalizePrefixedIds(record.test_ids, "file:"),
+		declared_test_targets: normalizePrefixedIds(record.declared_test_targets, "file:"),
+		likely_test_targets: normalizePrefixedIds(record.likely_test_targets, "file:"),
+		tested_by: normalizePrefixedIds(record.tested_by, "file:"),
 		evidence: normalizeEvidence(record.evidence)
 	};
 }
 function normalizeStringArray(value) {
 	if (!Array.isArray(value)) return [];
-	return value.filter((item) => typeof item === "string" && item.trim().length > 0);
+	return dedupeStrings(value.filter((item) => typeof item === "string").map((item) => item.trim()));
 }
 function normalizePrefixedIds(value, prefix) {
 	return normalizeStringArray(value).filter((item) => item.startsWith(prefix));
 }
 function normalizeEvidence(value) {
 	if (!Array.isArray(value)) return [];
-	return value.flatMap((item) => {
+	return dedupeRecords(value.flatMap((item) => {
 		if (!item || typeof item !== "object" || Array.isArray(item)) return [];
 		const record = item;
-		if (typeof record.kind !== "string" || record.kind.trim().length === 0) return [];
-		if (typeof record.value !== "string" || record.value.trim().length === 0) return [];
+		const kind = typeof record.kind === "string" ? record.kind.trim() : "";
+		const recordValue = typeof record.value === "string" ? record.value.trim() : "";
+		if (kind.length === 0) return [];
+		if (recordValue.length === 0) return [];
 		return [{
-			kind: record.kind,
-			value: record.value
+			kind,
+			value: recordValue
 		}];
-	});
+	}), (item) => `${item.kind}\0${item.value}`);
 }
-function normalizeSymbols(value, path) {
+function normalizeSymbols(value, path, exports) {
 	if (!Array.isArray(value)) return [];
-	return value.flatMap((item) => {
+	const exportedNames = new Set(exports);
+	return dedupeRecords(value.flatMap((item) => {
 		if (typeof item === "string") {
 			const name = item.trim();
 			if (!name || !path) return [];
@@ -3054,8 +4453,7 @@ function normalizeSymbols(value, path) {
 				id: `symbol:${path}#${name}`,
 				kind: "symbol",
 				name,
-				exported: false,
-				summary: `Symbol named ${name}.`
+				exported: exportedNames.has(name)
 			}];
 		}
 		if (!item || typeof item !== "object" || Array.isArray(item)) return [];
@@ -3063,14 +4461,36 @@ function normalizeSymbols(value, path) {
 		const rawId = typeof record.id === "string" && record.id.startsWith("symbol:") ? record.id : void 0;
 		const name = typeof record.name === "string" && record.name.trim().length > 0 ? record.name : rawId?.slice(rawId.lastIndexOf("#") + 1);
 		if (!name || !path) return [];
-		return [{
+		const summary = typeof record.summary === "string" && record.summary.trim().length > 0 ? record.summary.trim() : "";
+		return [removeUndefinedValues({
 			id: rawId ?? `symbol:${path}#${name}`,
-			kind: typeof record.kind === "string" && record.kind.trim().length > 0 ? record.kind : "symbol",
+			kind: typeof record.kind === "string" && record.kind.trim().length > 0 ? record.kind.trim() : "symbol",
 			name,
-			exported: typeof record.exported === "boolean" ? record.exported : false,
-			summary: typeof record.summary === "string" && record.summary.trim().length > 0 ? record.summary : `Symbol named ${name}.`
-		}];
-	});
+			exported: exportedNames.has(name) || (typeof record.exported === "boolean" ? record.exported : false),
+			summary: summary && !isGenericSymbolSummary$1(summary, name) ? summary : void 0
+		})];
+	}), (item) => String(item.id));
+}
+function dedupeStrings(values) {
+	return [...new Set(values.filter((value) => value.length > 0))];
+}
+function dedupeRecords(values, keyFor) {
+	const seen = /* @__PURE__ */ new Set();
+	const deduped = [];
+	for (const value of values) {
+		const key = keyFor(value);
+		if (seen.has(key)) continue;
+		seen.add(key);
+		deduped.push(value);
+	}
+	return deduped;
+}
+function removeUndefinedValues(record) {
+	return Object.fromEntries(Object.entries(record).filter(([, value]) => value !== void 0));
+}
+function isGenericSymbolSummary$1(summary, name) {
+	const normalizedSummary = summary.trim().replace(/\s+/g, " ");
+	return normalizedSummary === `Symbol named ${name}.` || normalizedSummary === `Symbol named ${name}` || normalizedSummary === name;
 }
 function extractTopLevelJsonObjects(text) {
 	const objects = [];
@@ -3472,11 +4892,11 @@ async function getL1SyncStatus(kbPath, kbReady, file) {
 		if (entry.path !== file.path || entry.size_bytes !== file.sizeBytes || entry.content_hash !== file.hash) return "changed";
 		return entry.scan_status;
 	} catch (error) {
-		if (isFileNotFoundError$1(error)) return "missing_entry";
+		if (isFileNotFoundError$2(error)) return "missing_entry";
 		return "invalid";
 	}
 }
-function isFileNotFoundError$1(error) {
+function isFileNotFoundError$2(error) {
 	return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
 }
 function assertKbSummarizeModelConfigured(model) {
@@ -3589,6 +5009,625 @@ function assertSafeResetPath(workspaceRoot, path) {
 function isNodeError(error) {
 	return error instanceof Error && "code" in error;
 }
+//#endregion
+//#region src/knowledge/search.ts
+var L1InMemoryIndex = class {
+	entriesById = /* @__PURE__ */ new Map();
+	postingsByToken = /* @__PURE__ */ new Map();
+	prefixTokensByPrefix = /* @__PURE__ */ new Map();
+	constructor(entries) {
+		for (const entry of entries) {
+			this.entriesById.set(entry.id, entry);
+			this.indexEntry(entry);
+		}
+		this.indexPrefixTokens();
+	}
+	get size() {
+		return this.entriesById.size;
+	}
+	search(query, options = {}) {
+		const tokens = tokenizeQuery(query);
+		const scoresByEntryId = /* @__PURE__ */ new Map();
+		const reasonsByEntryId = /* @__PURE__ */ new Map();
+		for (const token of tokens) {
+			this.addMatches(token, 1, scoresByEntryId, reasonsByEntryId);
+			if (token.length >= 4) this.addPrefixMatches(token, scoresByEntryId, reasonsByEntryId);
+		}
+		const limit = options.limit ?? 10;
+		return [...scoresByEntryId.entries()].map(([entryId, score]) => {
+			const entry = this.entriesById.get(entryId);
+			if (!entry) return;
+			return {
+				id: entry.id,
+				path: entry.path,
+				score: Math.round(score * 100) / 100,
+				summary: entry.summary,
+				contentHash: entry.content_hash,
+				scanStatus: entry.scan_status,
+				reasons: [...(reasonsByEntryId.get(entryId) ?? /* @__PURE__ */ new Map()).entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).map(([reason]) => reason).slice(0, 6)
+			};
+		}).filter((match) => Boolean(match)).sort((a, b) => b.score - a.score || a.path.localeCompare(b.path)).slice(0, limit);
+	}
+	getEntry(id) {
+		return this.entriesById.get(id);
+	}
+	indexEntry(entry) {
+		this.addField(entry, "path", [entry.path, basename(entry.path)], 6);
+		this.addField(entry, "symbol", entry.symbols.flatMap((symbol) => [
+			symbol.name,
+			symbol.kind,
+			symbol.summary
+		].filter(isString)), 10);
+		this.addField(entry, "export", entry.exports, 9);
+		this.addField(entry, "responsibility", entry.responsibilities, 6);
+		this.addField(entry, "summary", [entry.summary], 5);
+		this.addField(entry, "import", entry.imports, 4);
+		this.addField(entry, "test", entry.test_ids, 4);
+		this.addField(entry, "relationship", [...entry.module_ids, ...entry.feature_ids], 3);
+		this.addField(entry, "evidence", entry.evidence.map((evidence) => evidence.value), 3);
+	}
+	addField(entry, field, values, weight) {
+		const tokens = new Set(values.flatMap(tokenizeText));
+		for (const token of tokens) {
+			const postings = this.postingsByToken.get(token) ?? [];
+			postings.push({
+				entryId: entry.id,
+				weight,
+				reason: `${formatField(field)} matched ${token}`
+			});
+			this.postingsByToken.set(token, postings);
+		}
+	}
+	addMatches(token, multiplier, scoresByEntryId, reasonsByEntryId) {
+		for (const posting of this.postingsByToken.get(token) ?? []) {
+			scoresByEntryId.set(posting.entryId, (scoresByEntryId.get(posting.entryId) ?? 0) + posting.weight * multiplier);
+			const reasons = reasonsByEntryId.get(posting.entryId) ?? /* @__PURE__ */ new Map();
+			reasons.set(posting.reason, Math.max(reasons.get(posting.reason) ?? 0, posting.weight * multiplier));
+			reasonsByEntryId.set(posting.entryId, reasons);
+		}
+	}
+	addPrefixMatches(token, scoresByEntryId, reasonsByEntryId) {
+		const matchedTokens = /* @__PURE__ */ new Set();
+		for (const indexedToken of this.prefixTokensByPrefix.get(token) ?? []) matchedTokens.add(indexedToken);
+		for (let prefixLength = 1; prefixLength < token.length; prefixLength += 1) {
+			const prefix = token.slice(0, prefixLength);
+			if (this.postingsByToken.has(prefix)) matchedTokens.add(prefix);
+		}
+		for (const indexedToken of matchedTokens) {
+			if (indexedToken === token) continue;
+			this.addMatches(indexedToken, .6, scoresByEntryId, reasonsByEntryId);
+		}
+	}
+	indexPrefixTokens() {
+		for (const indexedToken of this.postingsByToken.keys()) for (let prefixLength = 4; prefixLength < indexedToken.length; prefixLength += 1) {
+			const prefix = indexedToken.slice(0, prefixLength);
+			const tokens = this.prefixTokensByPrefix.get(prefix) ?? [];
+			tokens.push(indexedToken);
+			this.prefixTokensByPrefix.set(prefix, tokens);
+		}
+	}
+};
+function buildL1InMemoryIndex(entries) {
+	return new L1InMemoryIndex(entries);
+}
+async function searchL1Knowledge(workspaceRoot, query, options = {}) {
+	const status = getKnowledgeStatus(workspaceRoot);
+	if (!status.kbExists || !status.kbIsDirectory) throw new Error("Run `topchester kb init` and `topchester kb compile` before searching the knowledge base.");
+	const loadResult = await loadL1FileEntries(status.kbPath);
+	const index = buildL1InMemoryIndex(loadResult.entries);
+	return {
+		workspaceRoot,
+		kbPath: status.kbPath,
+		query,
+		entryCount: index.size,
+		invalidEntryCount: loadResult.invalidEntryCount,
+		matches: index.search(query, options)
+	};
+}
+function createL1ContextPackFromIndex(source, query, options = {}) {
+	const limit = options.limit ?? 8;
+	const minScore = options.minScore ?? 12;
+	const relevantFiles = source.index.search(query, { limit: Math.max(limit * 3, limit) }).filter((match) => match.score >= minScore).slice(0, limit).map((match) => {
+		const entry = source.index.getEntry(match.id);
+		if (!entry) return;
+		return {
+			id: match.id,
+			path: match.path,
+			score: match.score,
+			reasons: match.reasons,
+			contentHash: match.contentHash,
+			scanStatus: match.scanStatus,
+			l1: compactL1Entry(entry),
+			fullL1: options.includeFullL1 ? entry : void 0
+		};
+	}).filter((file) => Boolean(file));
+	const warnings = relevantFiles.length === 0 ? ["No L1 entries met the context pack score threshold."] : [];
+	return {
+		workspaceRoot: source.workspaceRoot,
+		kbPath: source.kbPath,
+		query,
+		entryCount: source.index.size,
+		invalidEntryCount: source.invalidEntryCount,
+		selection: {
+			limit,
+			minScore
+		},
+		drift: {
+			status: "unchecked",
+			warnings: ["L1 context pack includes stored scan statuses; exact file-hash drift check has not run yet."]
+		},
+		summary: summarizeContextPack(query, relevantFiles),
+		warnings,
+		relevantFiles
+	};
+}
+async function createL1ContextPack(workspaceRoot, query, options = {}) {
+	const limit = options.limit ?? 8;
+	const minScore = options.minScore ?? 12;
+	const status = getKnowledgeStatus(workspaceRoot);
+	if (!status.kbExists || !status.kbIsDirectory) throw new Error("Run `topchester kb init` and `topchester kb compile` before creating a context pack.");
+	const loadResult = await loadL1FileEntries(status.kbPath);
+	const index = buildL1InMemoryIndex(loadResult.entries);
+	return createL1ContextPackFromIndex({
+		workspaceRoot,
+		kbPath: status.kbPath,
+		index,
+		invalidEntryCount: loadResult.invalidEntryCount
+	}, query, {
+		limit,
+		minScore,
+		includeFullL1: options.includeFullL1
+	});
+}
+function formatL1KnowledgeSearchResult(result) {
+	return [
+		"KB search",
+		`workspace: ${result.workspaceRoot}`,
+		`knowledge folder: ${result.kbPath} [ok]`,
+		`query: ${result.query}`,
+		`entries indexed: ${result.entryCount}`,
+		`invalid L1 entries skipped: ${result.invalidEntryCount}`,
+		`matches: ${result.matches.length}`,
+		...result.matches.length === 0 ? ["state: no L1 matches found"] : [""],
+		...result.matches.flatMap((match) => [
+			`${match.score}\t${match.path}\t${match.scanStatus}\t${match.contentHash}`,
+			`  reasons: ${match.reasons.join("; ") || "score match"}`,
+			`  summary: ${match.summary}`
+		]),
+		"----",
+		`total matches: ${result.matches.length}`
+	];
+}
+function formatL1ContextPackResult(result) {
+	return [
+		"KB context",
+		`workspace: ${result.workspaceRoot}`,
+		`knowledge folder: ${result.kbPath} [ok]`,
+		`query: ${result.query}`,
+		`entries indexed: ${result.entryCount}`,
+		`invalid L1 entries skipped: ${result.invalidEntryCount}`,
+		`selection: top ${result.selection.limit}, min score ${result.selection.minScore}`,
+		`drift: ${result.drift.status}`,
+		`relevant files: ${result.relevantFiles.length}`,
+		`summary: ${result.summary}`,
+		...result.warnings.map((warning) => `warning: ${warning}`),
+		"",
+		...result.relevantFiles.flatMap((file) => [
+			`${file.score}\t${file.path}\t${file.scanStatus}\t${file.contentHash}`,
+			`  reasons: ${file.reasons.join("; ") || "score match"}`,
+			`  responsibilities: ${(file.l1.responsibilities ?? []).join("; ") || "(none)"}`,
+			`  symbols: ${(file.l1.symbols ?? []).map((symbol) => symbol.name).join(", ") || "(none)"}`,
+			`  imports: ${(file.l1.imports ?? []).join(", ") || "(none)"}`,
+			`  exports: ${(file.l1.exports ?? []).join(", ") || "(none)"}`,
+			`  tests: ${(file.l1.test_ids ?? []).join(", ") || "(none)"}`
+		]),
+		"----",
+		`total relevant files: ${result.relevantFiles.length}`
+	];
+}
+function formatL1ContextPackForPrompt(result) {
+	return [
+		"Topchester KB context pack:",
+		"Use this as orientation only. For task-critical facts, read current source files before editing or making exact claims.",
+		"## -- kb summary start",
+		"```json",
+		JSON.stringify(stripEmptyContainers({
+			query: result.query,
+			summary: result.summary,
+			drift: result.drift,
+			warnings: result.warnings,
+			relevantFiles: result.relevantFiles.map((file) => ({
+				id: file.id,
+				path: file.path,
+				score: file.score,
+				reasons: file.reasons,
+				contentHash: file.contentHash,
+				scanStatus: file.scanStatus,
+				l1: {
+					summary: file.l1.summary,
+					file_role: file.l1.file_role,
+					responsibilities: file.l1.responsibilities,
+					symbols: file.l1.symbols,
+					imports: file.l1.imports,
+					exports: file.l1.exports,
+					module_ids: file.l1.module_ids,
+					feature_ids: file.l1.feature_ids,
+					test_ids: file.l1.test_ids,
+					declared_test_targets: file.l1.declared_test_targets,
+					likely_test_targets: file.l1.likely_test_targets,
+					tested_by: file.l1.tested_by,
+					confidence: file.l1.confidence
+				}
+			}))
+		})),
+		"```",
+		"## -- kb summary end"
+	].join("\n");
+}
+async function loadL1FileEntries(kbPath) {
+	const entryPaths = await listJsonFiles(join(kbPath, "l1-files")).catch((error) => {
+		if (isFileNotFoundError$1(error)) return [];
+		throw error;
+	});
+	const parsedEntries = await Promise.all(entryPaths.map(loadL1FileEntry));
+	const entries = parsedEntries.filter((entry) => Boolean(entry));
+	return {
+		entries,
+		invalidEntryCount: parsedEntries.length - entries.length
+	};
+}
+async function loadL1FileEntry(entryPath) {
+	try {
+		return parseL1FileEntry(JSON.parse(await readFile(entryPath, "utf8")));
+	} catch {
+		return;
+	}
+}
+function summarizeContextPack(query, files) {
+	if (files.length === 0) return `No strong L1 matches were found for "${query}".`;
+	const paths = files.slice(0, 5).map((file) => file.path);
+	return `Likely relevant L1 files for "${query}": ${paths.join(", ")}${files.length > paths.length ? ", ..." : ""}.`;
+}
+function compactL1Entry(entry) {
+	const responsibilities = take(entry.responsibilities, 5);
+	const symbols = take(entry.symbols, 12).map(compactSymbol);
+	const imports = take(entry.imports, 20);
+	const exports = take(entry.exports, 20);
+	const moduleIds = take(entry.module_ids, 10);
+	const featureIds = take(entry.feature_ids, 10);
+	const testIds = take(entry.test_ids, 10);
+	const declaredTestTargets = take(entry.declared_test_targets, 10);
+	const likelyTestTargets = take(entry.likely_test_targets, 10);
+	const testedBy = take(entry.tested_by, 10);
+	return stripUndefinedProperties({
+		file_role: entry.file_role,
+		summary: entry.summary,
+		responsibilities: nonEmptyArray(responsibilities),
+		symbols: nonEmptyArray(symbols),
+		imports: nonEmptyArray(imports),
+		exports: nonEmptyArray(exports),
+		module_ids: nonEmptyArray(moduleIds),
+		feature_ids: nonEmptyArray(featureIds),
+		test_ids: nonEmptyArray(testIds),
+		declared_test_targets: nonEmptyArray(declaredTestTargets),
+		likely_test_targets: nonEmptyArray(likelyTestTargets),
+		tested_by: nonEmptyArray(testedBy),
+		confidence: entry.confidence
+	});
+}
+function take(items, count) {
+	return items.slice(0, count);
+}
+function compactSymbol(symbol) {
+	const compacted = {
+		name: symbol.name,
+		exported: symbol.exported,
+		kind: symbol.kind === "symbol" ? void 0 : symbol.kind,
+		summary: symbol.summary && !isGenericSymbolSummary(symbol.summary, symbol.name) ? symbol.summary : void 0
+	};
+	return compacted.kind || compacted.summary ? compacted : {
+		name: compacted.name,
+		exported: compacted.exported
+	};
+}
+function stripEmptyContainers(value) {
+	if (Array.isArray(value)) {
+		const stripped = value.map(stripEmptyContainers).filter((item) => item !== void 0);
+		return stripped.length > 0 ? stripped : void 0;
+	}
+	if (value && typeof value === "object") {
+		const entries = Object.entries(value).map(([key, item]) => [key, stripEmptyContainers(item)]).filter(([, item]) => item !== void 0);
+		return entries.length > 0 ? Object.fromEntries(entries) : void 0;
+	}
+	return value;
+}
+function stripUndefinedProperties(value) {
+	return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== void 0));
+}
+function nonEmptyArray(items) {
+	return items.length > 0 ? items : void 0;
+}
+function isGenericSymbolSummary(summary, name) {
+	const normalizedSummary = summary.trim().replace(/\s+/g, " ");
+	return normalizedSummary === `Symbol named ${name}.` || normalizedSummary === `Symbol named ${name}` || normalizedSummary === name;
+}
+async function listJsonFiles(directory) {
+	const entries = await readdir(directory, { withFileTypes: true });
+	const files = [];
+	for (const entry of entries) {
+		const entryPath = join(directory, entry.name);
+		if (entry.isDirectory()) files.push(...await listJsonFiles(entryPath));
+		else if (entry.isFile() && entry.name.endsWith(".json")) files.push(entryPath);
+	}
+	return files.sort();
+}
+function tokenizeQuery(text) {
+	return [...new Set(tokenizeText(text).filter((token) => !queryStopWords.has(token)))];
+}
+function tokenizeText(text) {
+	const rawTokens = text.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").toLowerCase().match(/[a-z0-9_]+/g) ?? [];
+	const tokens = [];
+	for (const rawToken of rawTokens) {
+		const token = rawToken.replace(/^_+|_+$/g, "");
+		if (!token || indexStopWords.has(token)) continue;
+		tokens.push(token);
+		const singular = singularizeToken(token);
+		if (singular !== token) tokens.push(singular);
+	}
+	return tokens;
+}
+function singularizeToken(token) {
+	if (token.length > 3 && token.endsWith("ies")) return `${token.slice(0, -3)}y`;
+	if (token.length > 3 && token.endsWith("s") && !token.endsWith("ss") && !token.endsWith("us")) return token.slice(0, -1);
+	return token;
+}
+function formatField(field) {
+	switch (field) {
+		case "path": return "path";
+		case "symbol": return "symbol";
+		case "export": return "export";
+		case "responsibility": return "responsibility";
+		case "summary": return "summary";
+		case "import": return "import";
+		case "test": return "test";
+		case "relationship": return "relationship";
+		case "evidence": return "evidence";
+	}
+}
+function isFileNotFoundError$1(error) {
+	return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+function isString(value) {
+	return typeof value === "string";
+}
+const indexStopWords = new Set([
+	"a",
+	"an",
+	"and",
+	"are",
+	"as",
+	"at",
+	"be",
+	"by",
+	"for",
+	"from",
+	"in",
+	"is",
+	"it",
+	"of",
+	"on",
+	"or",
+	"the",
+	"to",
+	"with"
+]);
+const queryStopWords = new Set([
+	...indexStopWords,
+	"error",
+	"here",
+	"log",
+	"see",
+	"se",
+	"tries",
+	"trying",
+	"user",
+	"when"
+]);
+//#endregion
+//#region src/tui/markdown.ts
+const codeFenceSentinel = "topchester-code-fence";
+function renderMarkdown(text, width) {
+	const lines = new Markdown(unwrapMarkdownCodeFences(text), 0, 0, getMarkdownTheme()).render(width);
+	const rendered = [];
+	let inCodeBlock = false;
+	for (const line of lines) {
+		if (line.includes(codeFenceSentinel)) {
+			inCodeBlock = !inCodeBlock;
+			continue;
+		}
+		rendered.push(inCodeBlock ? applyCodeBlockBackground(line) : line);
+	}
+	return rendered;
+}
+function unwrapMarkdownCodeFences(text) {
+	return text.replace(/^```(?:markdown|md)\s*\n([\s\S]*?)\n```$/gim, "$1");
+}
+function getMarkdownTheme() {
+	return {
+		heading: ui.label,
+		link: ui.label,
+		linkUrl: ui.muted,
+		code: ui.ok,
+		codeBlock: (text) => text,
+		codeBlockBorder: (text) => `${codeFenceSentinel}${ui.muted(text)}`,
+		quote: ui.warn,
+		quoteBorder: ui.warn,
+		hr: ui.muted,
+		listBullet: ui.label,
+		bold: (text) => decorate(text, "\x1B[1m", "\x1B[22m"),
+		italic: (text) => decorate(text, "\x1B[3m", "\x1B[23m"),
+		strikethrough: (text) => decorate(text, "\x1B[9m", "\x1B[29m"),
+		underline: (text) => decorate(text, "\x1B[4m", "\x1B[24m"),
+		codeBlockIndent: "  ",
+		highlightCode(code, lang) {
+			const validLanguage = lang && supportsLanguage(lang) ? lang : void 0;
+			if (!validLanguage) return code.split("\n");
+			try {
+				return highlight(code, {
+					language: validLanguage,
+					ignoreIllegals: true
+				}).split("\n");
+			} catch {
+				return code.split("\n");
+			}
+		}
+	};
+}
+function decorate(text, open, close) {
+	if (!shouldUseAnsi()) return text;
+	return `${open}${text}${close}`;
+}
+function applyCodeBlockBackground(line) {
+	if (!shouldUseAnsi()) return line;
+	const background = "\x1B[48;5;235m";
+	const reset = "\x1B[0m";
+	return `${background}${line.split(reset).join(`${reset}${background}`)}${reset}`;
+}
+function shouldUseAnsi() {
+	if (process.env.NO_COLOR) return false;
+	if (process.env.FORCE_COLOR && process.env.FORCE_COLOR !== "0") return true;
+	return stdout.isTTY === true;
+}
+//#endregion
+//#region src/tui/messages.ts
+function systemMessage(text) {
+	return {
+		kind: "system",
+		text
+	};
+}
+function userMessage(text) {
+	return {
+		kind: "user",
+		text
+	};
+}
+function agentMessage(text, meta) {
+	return {
+		kind: "agent",
+		text,
+		meta
+	};
+}
+function toolCallMessage(call, label, resultSummary) {
+	return resultSummary === void 0 ? {
+		kind: "tool_call",
+		call,
+		label
+	} : {
+		kind: "tool_call",
+		call,
+		label,
+		resultSummary
+	};
+}
+function modalMessage(message) {
+	return {
+		kind: "modal",
+		...message
+	};
+}
+function renderChatMessage(message, options = {}) {
+	if (message.kind === "modal") return renderChatModal(message, options.selectedActionIndex);
+	if (message.kind === "tool_call") return renderToolCallMessage(message);
+	if (message.text.length === 0) return [""];
+	const lines = message.kind === "agent" && options.width !== void 0 ? renderMarkdown(message.text, Math.max(1, options.width - getPrefix(message.kind).length)) : message.text.split("\n");
+	if (message.kind === "user") return renderUserMessage(lines);
+	if (message.kind === "system") return renderSystemMessage(lines);
+	const prefix = getPrefix(message.kind);
+	const rendered = prefix.length === 0 ? lines : lines.map((line, index) => `${index === 0 ? prefix : " ".repeat(prefix.length)}${line}`);
+	if (message.meta) {
+		const metaText = `↳ ${message.meta}`;
+		rendered.push(` ${ui.label("─".repeat(metaText.length))}`, ` ${ui.label(metaText)}`);
+	}
+	return rendered;
+}
+function renderUserMessage(lines) {
+	const border = "▌";
+	const rendered = lines.map((line) => `${border} ${line}`);
+	return [
+		`${border} `,
+		...rendered,
+		`${border} `
+	];
+}
+function renderSystemMessage(lines) {
+	const bodyPrefix = "   ";
+	return [` ${ui.ok("✦")} ${ui.label("System")}:`, ...lines.map((line) => `${bodyPrefix}${formatSystemBodyLine(line)}`)];
+}
+function formatSystemBodyLine(line) {
+	return expandTabs(line).replace(/\(changed \+\d+\/-\d+\)$/u, (summary) => ui.muted(summary)).replace(/\(created \+\d+\)$/u, (summary) => ui.muted(summary));
+}
+function renderToolCallMessage(message) {
+	const visibleLabel = message.resultSummary && !message.label.includes(message.resultSummary) ? `${message.label} ${message.resultSummary}` : message.label;
+	return [`   ${ui.muted(expandTabs(visibleLabel))}`];
+}
+function expandTabs(line) {
+	let column = 0;
+	let expanded = "";
+	for (const char of line) {
+		if (char === "	") {
+			const spaces = 4 - column % 4;
+			expanded += " ".repeat(spaces);
+			column += spaces;
+			continue;
+		}
+		expanded += char;
+		column += 1;
+	}
+	return expanded;
+}
+function getPrefix(kind) {
+	switch (kind) {
+		case "agent": return " ";
+		case "user": return `${ui.label("You")}: `;
+		case "system": return `${ui.label("System")}: `;
+	}
+}
+function renderChatModal(message, selectedActionIndex) {
+	const icon = message.tone === "warning" ? "⚠️" : "ℹ️";
+	const title = message.tone === "warning" ? ui.warn(message.title) : ui.label(message.title);
+	const bodyLines = message.body ? ["", ...message.body.split("\n")] : [];
+	const actionLines = message.actions.map((action, index) => {
+		return `${selectedActionIndex === index ? ">" : " "} ${index + 1}) ${action.label}`;
+	});
+	const contentLines = [
+		`${icon}  ${title}:`,
+		...bodyLines,
+		"",
+		...actionLines
+	];
+	const contentWidth = Math.max(...contentLines.map(stripAnsi$1).map((line) => line.length), 1);
+	const top = `╭${"─".repeat(contentWidth + 2)}╮`;
+	const bottom = `╰${"─".repeat(contentWidth + 2)}╯`;
+	return [
+		top,
+		...contentLines.map((line) => `│ ${line}${" ".repeat(contentWidth - stripAnsi$1(line).length)} │`),
+		bottom
+	];
+}
+function stripAnsi$1(text) {
+	let plain = "";
+	for (let index = 0; index < text.length; index += 1) {
+		if (text.charCodeAt(index) === 27 && text[index + 1] === "[") {
+			index += 2;
+			while (index < text.length && text[index] !== "m") index += 1;
+			continue;
+		}
+		plain += text[index];
+	}
+	return plain;
+}
 const isoTimestampSchema = z.string().datetime({ offset: true });
 const jsonValueSchema = z.lazy(() => z.union([
 	z.string(),
@@ -3626,6 +5665,19 @@ const toolCallPayloadSchema = z.object({
 	label: z.string(),
 	call: z.record(z.string(), jsonValueSchema)
 });
+const taskPlanItemPayloadSchema = z.object({
+	text: z.string(),
+	status: z.enum([
+		"pending",
+		"in_progress",
+		"completed"
+	])
+});
+const taskPlanPayloadSchema = z.object({
+	kind: z.literal("task_plan"),
+	items: z.array(taskPlanItemPayloadSchema),
+	updatedAt: isoTimestampSchema
+});
 const statusPayloadSchema = z.object({
 	kind: z.literal("status"),
 	status: z.string()
@@ -3647,6 +5699,7 @@ const choicePayloadSchema = z.object({
 const sessionEventPayloadSchema = z.discriminatedUnion("kind", [
 	messagePayloadSchema,
 	toolCallPayloadSchema,
+	taskPlanPayloadSchema,
 	statusPayloadSchema,
 	knowledgeStatusPayloadSchema,
 	choicePayloadSchema
@@ -3727,6 +5780,7 @@ async function resolveLatestSessionId(workspaceRoot) {
 function rehydrateSession(events) {
 	const messages = [];
 	let status;
+	let taskPlan;
 	let visibleOnlyActionValues = /* @__PURE__ */ new Set();
 	for (const event of events) switch (event.kind) {
 		case "message":
@@ -3740,10 +5794,13 @@ function rehydrateSession(events) {
 			if (event.role === "user") visibleOnlyActionValues = /* @__PURE__ */ new Set();
 			break;
 		case "tool_call":
-			messages.push({
-				kind: "system",
-				text: event.label
-			});
+			messages.push(toolCallMessage(event.call, event.label));
+			break;
+		case "task_plan":
+			taskPlan = {
+				items: event.items,
+				updatedAt: event.updatedAt
+			};
 			break;
 		case "knowledge_status": break;
 		case "choice":
@@ -3762,7 +5819,8 @@ function rehydrateSession(events) {
 	}
 	return {
 		messages,
-		status
+		status,
+		...taskPlan === void 0 ? {} : { taskPlan }
 	};
 }
 function buildHandle(sessionDir, metadata) {
@@ -4140,188 +6198,70 @@ async function executeKbCommand(args, context) {
 	return { messages: ["Usage: /kb init, /kb compile, /kb sync, /kb reset, or /kb status"] };
 }
 //#endregion
-//#region src/tui/markdown.ts
-const codeFenceSentinel = "topchester-code-fence";
-function renderMarkdown(text, width) {
-	const lines = new Markdown(unwrapMarkdownCodeFences(text), 0, 0, getMarkdownTheme()).render(width);
-	const rendered = [];
-	let inCodeBlock = false;
-	for (const line of lines) {
-		if (line.includes(codeFenceSentinel)) {
-			inCodeBlock = !inCodeBlock;
-			continue;
-		}
-		rendered.push(inCodeBlock ? applyCodeBlockBackground(line) : line);
+//#region src/agent/events.ts
+const ABORT_CHOICE_VALUE = "__topchester_abort__";
+const agentEvent = {
+	status(status) {
+		return {
+			type: "status",
+			status
+		};
+	},
+	systemMessage(text) {
+		return {
+			type: "message",
+			role: "system",
+			text
+		};
+	},
+	assistantMessage(text, meta) {
+		return meta === void 0 ? {
+			type: "message",
+			role: "assistant",
+			text
+		} : {
+			type: "message",
+			role: "assistant",
+			text,
+			meta
+		};
+	},
+	toolCall(call, label) {
+		return {
+			type: "tool_call",
+			call,
+			label
+		};
+	},
+	taskPlan(plan) {
+		return {
+			type: "task_plan",
+			plan
+		};
+	},
+	knowledgeStatus(status, guidance) {
+		return guidance === void 0 ? {
+			type: "knowledge_status",
+			status
+		} : {
+			type: "knowledge_status",
+			status,
+			guidance
+		};
+	},
+	choice(options) {
+		return {
+			type: "choice",
+			...options
+		};
 	}
-	return rendered;
-}
-function unwrapMarkdownCodeFences(text) {
-	return text.replace(/^```(?:markdown|md)\s*\n([\s\S]*?)\n```$/gim, "$1");
-}
-function getMarkdownTheme() {
-	return {
-		heading: ui.label,
-		link: ui.label,
-		linkUrl: ui.muted,
-		code: ui.ok,
-		codeBlock: (text) => text,
-		codeBlockBorder: (text) => `${codeFenceSentinel}${ui.muted(text)}`,
-		quote: ui.warn,
-		quoteBorder: ui.warn,
-		hr: ui.muted,
-		listBullet: ui.label,
-		bold: (text) => decorate(text, "\x1B[1m", "\x1B[22m"),
-		italic: (text) => decorate(text, "\x1B[3m", "\x1B[23m"),
-		strikethrough: (text) => decorate(text, "\x1B[9m", "\x1B[29m"),
-		underline: (text) => decorate(text, "\x1B[4m", "\x1B[24m"),
-		codeBlockIndent: "  ",
-		highlightCode(code, lang) {
-			const validLanguage = lang && supportsLanguage(lang) ? lang : void 0;
-			if (!validLanguage) return code.split("\n");
-			try {
-				return highlight(code, {
-					language: validLanguage,
-					ignoreIllegals: true
-				}).split("\n");
-			} catch {
-				return code.split("\n");
-			}
-		}
-	};
-}
-function decorate(text, open, close) {
-	if (!shouldUseAnsi()) return text;
-	return `${open}${text}${close}`;
-}
-function applyCodeBlockBackground(line) {
-	if (!shouldUseAnsi()) return line;
-	const background = "\x1B[48;5;235m";
-	const reset = "\x1B[0m";
-	return `${background}${line.split(reset).join(`${reset}${background}`)}${reset}`;
-}
-function shouldUseAnsi() {
-	if (process.env.NO_COLOR) return false;
-	if (process.env.FORCE_COLOR && process.env.FORCE_COLOR !== "0") return true;
-	return stdout.isTTY === true;
-}
-//#endregion
-//#region src/tui/messages.ts
-function systemMessage(text) {
-	return {
-		kind: "system",
-		text
-	};
-}
-function userMessage(text) {
-	return {
-		kind: "user",
-		text
-	};
-}
-function agentMessage(text, meta) {
-	return {
-		kind: "agent",
-		text,
-		meta
-	};
-}
-function modalMessage(message) {
-	return {
-		kind: "modal",
-		...message
+};
+function choiceAction(label, value) {
+	return value === void 0 ? { label } : {
+		label,
+		value
 	};
 }
-function renderChatMessage(message, options = {}) {
-	if (message.kind === "modal") return renderChatModal(message, options.selectedActionIndex);
-	if (message.text.length === 0) return [""];
-	const lines = message.kind === "agent" && options.width !== void 0 ? renderMarkdown(message.text, Math.max(1, options.width - getPrefix(message.kind).length)) : message.text.split("\n");
-	if (message.kind === "user") return renderUserMessage(lines);
-	if (message.kind === "system") return renderSystemMessage(lines);
-	const prefix = getPrefix(message.kind);
-	const rendered = prefix.length === 0 ? lines : lines.map((line, index) => `${index === 0 ? prefix : " ".repeat(prefix.length)}${line}`);
-	if (message.meta) {
-		const metaText = `↳ ${message.meta}`;
-		rendered.push(` ${ui.label("─".repeat(metaText.length))}`, ` ${ui.label(metaText)}`);
-	}
-	return rendered;
-}
-function renderUserMessage(lines) {
-	const border = "▌";
-	const rendered = lines.map((line) => `${border} ${line}`);
-	return [
-		`${border} `,
-		...rendered,
-		`${border} `
-	];
-}
-function renderSystemMessage(lines) {
-	const bodyPrefix = "   ";
-	return [` ${ui.ok("✦")} ${ui.label("System")}:`, ...lines.map((line) => `${bodyPrefix}${formatSystemBodyLine(line)}`)];
-}
-function formatSystemBodyLine(line) {
-	const expandedLine = expandTabs(line);
-	if (isToolCallLine(line)) return ui.muted(expandedLine);
-	return expandedLine.replace(/\(changed \+\d+\/-\d+\)$/u, (summary) => ui.muted(summary));
-}
-function isToolCallLine(line) {
-	return /^(read_file|list_files|grep|find_file|edit_file|inspect_command): /u.test(line);
-}
-function expandTabs(line) {
-	let column = 0;
-	let expanded = "";
-	for (const char of line) {
-		if (char === "	") {
-			const spaces = 4 - column % 4;
-			expanded += " ".repeat(spaces);
-			column += spaces;
-			continue;
-		}
-		expanded += char;
-		column += 1;
-	}
-	return expanded;
-}
-function getPrefix(kind) {
-	switch (kind) {
-		case "agent": return " ";
-		case "user": return `${ui.label("You")}: `;
-		case "system": return `${ui.label("System")}: `;
-	}
-}
-function renderChatModal(message, selectedActionIndex) {
-	const icon = message.tone === "warning" ? "⚠️" : "ℹ️";
-	const title = message.tone === "warning" ? ui.warn(message.title) : ui.label(message.title);
-	const bodyLines = message.body ? ["", ...message.body.split("\n")] : [];
-	const actionLines = message.actions.map((action, index) => {
-		return `${selectedActionIndex === index ? ">" : " "} ${index + 1}) ${action.label}`;
-	});
-	const contentLines = [
-		`${icon}  ${title}:`,
-		...bodyLines,
-		"",
-		...actionLines
-	];
-	const contentWidth = Math.max(...contentLines.map(stripAnsi$1).map((line) => line.length), 1);
-	const top = `╭${"─".repeat(contentWidth + 2)}╮`;
-	const bottom = `╰${"─".repeat(contentWidth + 2)}╯`;
-	return [
-		top,
-		...contentLines.map((line) => `│ ${line}${" ".repeat(contentWidth - stripAnsi$1(line).length)} │`),
-		bottom
-	];
-}
-function stripAnsi$1(text) {
-	let plain = "";
-	for (let index = 0; index < text.length; index += 1) {
-		if (text.charCodeAt(index) === 27 && text[index + 1] === "[") {
-			index += 2;
-			while (index < text.length && text[index] !== "m") index += 1;
-			continue;
-		}
-		plain += text[index];
-	}
-	return plain;
-}
 //#endregion
 //#region src/tui/keys.ts
 function isUpKey(data) {
@@ -4333,6 +6273,9 @@ function isDownKey(data) {
 function isEnterKey(data) {
 	return matchesKey(data, "enter") || data === "\n" || data === "\r";
 }
+function isNewLineKey(data) {
+	return matchesKey(data, "shift+enter") || matchesKey(data, "alt+enter") || matchesKey(data, "ctrl+enter") || data === "\x1B\r" || data === "\x1B[13;2~";
+}
 function isTabKey(data) {
 	return matchesKey(data, "tab") || data === "	";
 }
@@ -4439,12 +6382,14 @@ function getStartupThreadMessages(context) {
 	lines.push("Ask Topchester what you want to change.");
 	return [systemMessage(lines.join("\n"))];
 }
-function renderStaticLayout(messages, folderName = "", modelLabel = "") {
+function renderStaticLayout(messages, folderName = "", modelLabel = "", taskPlan) {
 	const threadLines = messages.flatMap((message) => renderChatMessage(message));
 	const status = formatStatusLine(folderName, modelLabel);
+	const planLines = taskPlan && taskPlan.items.length > 0 ? [...formatTaskPlanForTui(taskPlan, 72), ""] : [];
 	return [
 		...threadLines,
 		"",
+		...planLines,
 		"┌──────────────────────────────────────────────────────────────────────┐",
 		"│ >                                                                    │",
 		"└──────────────────────────────────────────────────────────────────────┘",
@@ -4526,23 +6471,35 @@ function stripAnsi(text) {
 }
 //#endregion
 //#region src/tui/layout.ts
+const PROMPT_VISIBLE_CONTENT_LINES = 5;
+const PASTE_PREVIEW_MIN_LINES = 6;
+const PASTE_PREVIEW_MIN_CHARS = 500;
+const BRACKETED_PASTE_START = "\x1B[200~";
+const BRACKETED_PASTE_END = "\x1B[201~";
 var ChatLayout = class {
 	terminal;
 	messages;
 	folderName;
 	modelLabel;
-	input = new Input();
+	inputFocused = false;
+	promptValue = "";
+	promptCursor = 0;
 	status = "ready";
 	knowledgeStatus;
 	ephemeralLine;
+	taskPlanNoticeLine;
 	noticeLine;
 	promptHint;
+	taskPlan;
 	cancelPending;
 	submitMessage;
 	submitCommand;
 	activeModalActionIndex = 0;
 	activeSlashSuggestionIndex = 0;
 	threadScrollOffset = 0;
+	pasteBuffer;
+	pasteCounter = 0;
+	pastedContent = /* @__PURE__ */ new Map();
 	promptHistory = new PromptHistory();
 	exitAgent;
 	transcriptMode;
@@ -4553,14 +6510,6 @@ var ChatLayout = class {
 		this.modelLabel = modelLabel;
 		this.exitAgent = typeof options === "function" ? options : options.exitAgent ?? (() => {});
 		this.transcriptMode = typeof options === "function" ? "viewport" : options.transcriptMode ?? "viewport";
-		this.input.onSubmit = (value) => {
-			if (value.trim().length > 0) {
-				const message = value.trim();
-				this.addMessage(userMessage(message));
-				this.input.setValue("");
-				this.submitUserInput(message);
-			}
-		};
 	}
 	addMessage(message) {
 		this.messages.push(message);
@@ -4573,6 +6522,24 @@ var ChatLayout = class {
 	setKnowledgeStatus(status) {
 		this.knowledgeStatus = formatKnowledgeFooterStatus(status);
 	}
+	setTaskPlan(plan) {
+		const change = detectTaskPlanChange(this.taskPlan, plan);
+		this.taskPlan = plan && plan.items.length > 0 ? plan : void 0;
+		return change;
+	}
+	setTaskPlanNotice(line) {
+		this.taskPlanNoticeLine = line;
+	}
+	clearTaskPlan(now = /* @__PURE__ */ new Date()) {
+		if (!this.taskPlan) return;
+		const cleared = {
+			items: [],
+			updatedAt: now.toISOString()
+		};
+		this.taskPlan = void 0;
+		this.taskPlanNoticeLine = void 0;
+		return cleared;
+	}
 	isReady() {
 		return this.status === "ready";
 	}
@@ -4595,26 +6562,33 @@ var ChatLayout = class {
 		this.submitCommand = submit;
 	}
 	setInputValue(value) {
-		this.input.setValue(value);
+		this.promptValue = value;
+		this.promptCursor = value.length;
+		this.pastedContent.clear();
+		this.pasteCounter = 0;
 	}
 	getConversationTurns() {
 		return this.messages.flatMap((message) => {
-			if (message.kind === "user" && message.modelContext !== false) return [{
-				role: "user",
-				text: message.text
-			}];
-			if (message.kind === "agent" && message.text !== "ready" && message.modelContext !== false) return [{
-				role: "assistant",
-				text: message.text
-			}];
-			return [];
+			switch (message.kind) {
+				case "user": return message.modelContext === false ? [] : [{
+					role: "user",
+					text: message.text
+				}];
+				case "agent": return message.text === "ready" || message.modelContext === false ? [] : [{
+					role: "assistant",
+					text: message.text
+				}];
+				case "system":
+				case "tool_call":
+				case "modal": return [];
+			}
 		});
 	}
 	get focused() {
-		return this.input.focused;
+		return this.inputFocused;
 	}
 	set focused(value) {
-		this.input.focused = value;
+		this.inputFocused = value;
 	}
 	handleInput(data) {
 		if (this.cancelPending && matchesKey(data, "escape")) {
@@ -4623,15 +6597,15 @@ var ChatLayout = class {
 		}
 		if (this.handleModalInput(data)) return;
 		if (this.handleSlashSuggestionInput(data)) return;
+		if (this.handlePromptPasteInput(data)) return;
+		if (this.handlePromptNewLineInput(data)) return;
+		if (this.handlePromptSubmitInput(data)) return;
 		if (this.handleThreadScrollInput(data)) return;
+		if (this.handlePromptVerticalCursorInput(data)) return;
 		if (this.handlePromptHistoryInput(data)) return;
-		const previousInput = this.input.getValue();
-		this.input.handleInput(data);
-		if (this.input.getValue() !== previousInput) this.promptHistory.resetBrowsing();
-	}
-	invalidate() {
-		this.input.invalidate();
+		this.handlePromptEditInput(data);
 	}
+	invalidate() {}
 	render(width) {
 		const safeWidth = Math.max(20, width);
 		const footerLines = this.getActiveModal() ? this.renderModalHelp(safeWidth) : this.renderPrompt(safeWidth);
@@ -4659,6 +6633,7 @@ var ChatLayout = class {
 			return [...this.renderThreadMessageLines(messageLines, innerWidth, width, message.kind === "user"), ...spacer];
 		});
 		if (this.ephemeralLine) lines.push(...this.renderThreadMessageLines([` ${this.ephemeralLine}`], innerWidth, width, false));
+		if (this.taskPlanNoticeLine) lines.push(...this.renderThreadMessageLines([` ${this.taskPlanNoticeLine}`], innerWidth, width, false));
 		if (this.noticeLine) lines.push(...this.renderThreadMessageLines([` ${this.noticeLine}`], innerWidth, width, false));
 		return lines;
 	}
@@ -4674,17 +6649,69 @@ var ChatLayout = class {
 		const bottom = `└${"─".repeat(Math.max(0, width - 2))}┘`;
 		const prefix = "> ";
 		const innerWidth = Math.max(1, width - 4 - 2);
-		const inputLine = this.promptHint ? truncateToWidth(ui.label(this.promptHint), innerWidth, "…", true) : truncateToWidth(renderInputWithoutPrompt(this.input, innerWidth), innerWidth, "…", true);
+		const inputLines = this.promptHint ? [truncateToWidth(ui.label(this.promptHint), innerWidth, "…", true)] : this.renderPromptInputLines(innerWidth);
 		const statusInnerWidth = Math.max(1, width - 2);
 		const status = truncateToWidth(` ${formatStatusLine(this.folderName, this.modelLabel, this.status, this.knowledgeStatus, statusInnerWidth)} `, width, "…", true);
 		return [
 			...this.renderSlashSuggestions(width),
+			...this.renderTaskPlan(width),
 			top,
-			`│ ${prefix}${inputLine} │`,
+			...inputLines.map((line, index) => `│ ${index === 0 ? prefix : "  "}${padPromptInputLine(line, innerWidth)} │`),
 			bottom,
 			status
 		];
 	}
+	renderPromptInputLines(innerWidth) {
+		const value = this.promptValue;
+		if (!value.includes("\n")) return [this.renderPromptLineWithCursor(value, this.promptCursor, innerWidth)];
+		const rows = this.getPromptRows(innerWidth);
+		const cursorRowIndex = rows.findIndex((row) => this.promptCursor >= row.start && this.promptCursor <= row.end);
+		const latestStart = Math.max(0, rows.length - PROMPT_VISIBLE_CONTENT_LINES);
+		const visibleStart = cursorRowIndex === -1 ? latestStart : Math.min(Math.max(0, cursorRowIndex - 2), latestStart);
+		return rows.slice(visibleStart, visibleStart + PROMPT_VISIBLE_CONTENT_LINES).map((row) => {
+			if (this.promptCursor >= row.start && this.promptCursor <= row.end) return this.renderPromptLineWithCursor(row.text, this.promptCursor - row.start, innerWidth);
+			return truncateToWidth(row.text.length === 0 ? " " : row.text, innerWidth, "…", true);
+		});
+	}
+	getPromptRows(width) {
+		const rows = [];
+		let offset = 0;
+		for (const line of this.promptValue.split("\n")) {
+			if (line.length === 0) rows.push({
+				text: "",
+				start: offset,
+				end: offset
+			});
+			else for (let index = 0; index < line.length; index += width) {
+				const text = line.slice(index, index + width);
+				rows.push({
+					text,
+					start: offset + index,
+					end: offset + index + text.length
+				});
+			}
+			offset += line.length + 1;
+		}
+		return rows.length > 0 ? rows : [{
+			text: "",
+			start: 0,
+			end: 0
+		}];
+	}
+	renderPromptLineWithCursor(text, cursor, width) {
+		const safeCursor = Math.max(0, Math.min(cursor, text.length));
+		const windowStart = safeCursor >= width ? safeCursor - width + 1 : 0;
+		const visibleText = text.slice(windowStart, windowStart + width);
+		const visibleCursor = safeCursor - windowStart;
+		const beforeCursor = visibleText.slice(0, visibleCursor);
+		const cursorChar = visibleText[visibleCursor] ?? " ";
+		const afterCursor = visibleText.slice(visibleCursor + cursorChar.length);
+		return truncateToWidth(`${beforeCursor}${this.inputFocused ? CURSOR_MARKER : ""}\u001b[7m${cursorChar}\u001b[27m${afterCursor}`, width, "…", true);
+	}
+	renderTaskPlan(width) {
+		if (!this.taskPlan) return [];
+		return formatTaskPlanForTui(this.taskPlan, Math.max(1, width));
+	}
 	renderSlashSuggestions(width) {
 		const suggestions = this.getSlashSuggestions();
 		if (suggestions.length === 0 || this.promptHint) return [];
@@ -4731,6 +6758,14 @@ var ChatLayout = class {
 				this.exitAgent();
 				return true;
 			}
+			if (action.value === "__topchester_abort__") {
+				this.addMessage({
+					kind: "user",
+					text: action.label,
+					modelContext: false
+				});
+				return true;
+			}
 			this.submitModalAction(action.value ?? action.label);
 			return true;
 		}
@@ -4773,17 +6808,196 @@ var ChatLayout = class {
 	handlePromptHistoryInput(data) {
 		if (this.promptHint) return false;
 		if (isUpKey(data)) {
-			const prompt = this.promptHistory.previous(this.input.getValue());
-			if (prompt !== void 0) this.input.setValue(prompt);
+			const prompt = this.promptHistory.previous(this.promptValue);
+			if (prompt !== void 0) {
+				this.promptValue = prompt;
+				this.promptCursor = prompt.length;
+			}
 			return true;
 		}
 		if (isDownKey(data)) {
 			const prompt = this.promptHistory.next();
-			if (prompt !== void 0) this.input.setValue(prompt);
+			if (prompt !== void 0) {
+				this.promptValue = prompt;
+				this.promptCursor = prompt.length;
+			}
+			return true;
+		}
+		return false;
+	}
+	handlePromptVerticalCursorInput(data) {
+		if (this.promptHint || !this.promptValue.includes("\n")) return false;
+		if (isUpKey(data)) {
+			if (this.canMovePromptCursorVertically(-1)) {
+				this.movePromptCursorVertically(-1);
+				return true;
+			}
+			if (this.promptCursor > 0) {
+				this.promptCursor = this.getCurrentPromptLineStart();
+				return true;
+			}
+			return false;
+		}
+		if (isDownKey(data)) {
+			if (this.canMovePromptCursorVertically(1)) {
+				this.movePromptCursorVertically(1);
+				return true;
+			}
+			if (this.promptCursor < this.promptValue.length) {
+				this.promptCursor = this.getCurrentPromptLineEnd();
+				return true;
+			}
+			return false;
+		}
+		return false;
+	}
+	canMovePromptCursorVertically(delta) {
+		const lines = this.promptValue.split("\n");
+		const current = this.getPromptLineCursor(lines);
+		if (delta === -1) return current.line > 0;
+		return current.line < lines.length - 1;
+	}
+	handlePromptNewLineInput(data) {
+		if (this.promptHint || !isNewLineKey(data)) return false;
+		this.insertPromptText("\n");
+		this.promptHistory.resetBrowsing();
+		return true;
+	}
+	handlePromptSubmitInput(data) {
+		if (this.promptHint || !isEnterKey(data)) return false;
+		this.submitPromptValue();
+		return true;
+	}
+	handlePromptPasteInput(data) {
+		if (this.promptHint) return false;
+		if (this.pasteBuffer !== void 0) {
+			this.pasteBuffer += data;
+			this.flushPromptPasteBuffer();
+			return true;
+		}
+		const startIndex = data.indexOf(BRACKETED_PASTE_START);
+		if (startIndex === -1) return false;
+		const beforePaste = data.slice(0, startIndex);
+		if (beforePaste.length > 0) this.insertPromptText(beforePaste);
+		this.pasteBuffer = data.slice(startIndex + 6);
+		this.flushPromptPasteBuffer();
+		this.promptHistory.resetBrowsing();
+		return true;
+	}
+	flushPromptPasteBuffer() {
+		if (this.pasteBuffer === void 0) return;
+		const endIndex = this.pasteBuffer.indexOf(BRACKETED_PASTE_END);
+		if (endIndex === -1) return;
+		const pasted = this.pasteBuffer.slice(0, endIndex);
+		const remaining = this.pasteBuffer.slice(endIndex + 6);
+		this.pasteBuffer = void 0;
+		this.insertPastedText(pasted);
+		if (remaining.length > 0) this.handleInput(remaining);
+	}
+	insertPastedText(text) {
+		const normalizedText = text.replace(/\r\n/g, "\n").replace(/\r/g, "\n").replace(/\t/g, "    ");
+		const trimmedText = normalizedText.trim();
+		if (trimmedText.length === 0) return;
+		const lineCount = trimmedText.split("\n").length;
+		if (lineCount >= PASTE_PREVIEW_MIN_LINES || trimmedText.length >= PASTE_PREVIEW_MIN_CHARS) {
+			this.pasteCounter += 1;
+			const marker = `[Pasted #${this.pasteCounter} ${lineCount} lines ${trimmedText.length} chars]`;
+			this.pastedContent.set(marker, trimmedText);
+			this.insertPromptText(marker);
+			return;
+		}
+		this.insertPromptText(normalizedText);
+	}
+	insertPromptText(text) {
+		this.promptValue = `${this.promptValue.slice(0, this.promptCursor)}${text}${this.promptValue.slice(this.promptCursor)}`;
+		this.promptCursor += text.length;
+	}
+	expandPastedContent(value) {
+		let expanded = value;
+		for (const [marker, content] of this.pastedContent) expanded = expanded.split(marker).join(content);
+		return expanded;
+	}
+	submitPromptValue() {
+		if (this.promptValue.trim().length === 0) return;
+		const message = this.expandPastedContent(this.promptValue).trim();
+		this.addMessage(userMessage(message));
+		this.promptValue = "";
+		this.promptCursor = 0;
+		this.pastedContent.clear();
+		this.pasteCounter = 0;
+		this.submitUserInput(message);
+	}
+	handlePromptEditInput(data) {
+		if (this.promptHint) return false;
+		if (matchesKey(data, "left") || data === "\x1B[D") {
+			this.promptCursor = Math.max(0, this.promptCursor - 1);
+			return true;
+		}
+		if (matchesKey(data, "right") || data === "\x1B[C") {
+			this.promptCursor = Math.min(this.promptValue.length, this.promptCursor + 1);
+			return true;
+		}
+		if (isHomeKey(data)) {
+			this.promptCursor = this.getCurrentPromptLineStart();
+			return true;
+		}
+		if (isEndKey(data)) {
+			this.promptCursor = this.getCurrentPromptLineEnd();
+			return true;
+		}
+		if (matchesKey(data, "backspace") || data === "" || data === "\b") {
+			if (this.promptCursor > 0) {
+				this.promptValue = `${this.promptValue.slice(0, this.promptCursor - 1)}${this.promptValue.slice(this.promptCursor)}`;
+				this.promptCursor -= 1;
+				this.promptHistory.resetBrowsing();
+			}
+			return true;
+		}
+		if (matchesKey(data, "delete") || data === "\x1B[3~") {
+			if (this.promptCursor < this.promptValue.length) {
+				this.promptValue = `${this.promptValue.slice(0, this.promptCursor)}${this.promptValue.slice(this.promptCursor + 1)}`;
+				this.promptHistory.resetBrowsing();
+			}
+			return true;
+		}
+		const printable = decodeKittyPrintable(data) ?? (isPrintableInput(data) ? data : void 0);
+		if (printable !== void 0) {
+			this.insertPromptText(printable);
+			this.promptHistory.resetBrowsing();
 			return true;
 		}
 		return false;
 	}
+	movePromptCursorVertically(delta) {
+		const lines = this.promptValue.split("\n");
+		const current = this.getPromptLineCursor(lines);
+		const targetLine = Math.max(0, Math.min(lines.length - 1, current.line + delta));
+		const targetColumn = Math.min(current.column, lines[targetLine]?.length ?? 0);
+		this.promptCursor = lines.slice(0, targetLine).reduce((total, line) => total + line.length + 1, 0) + targetColumn;
+	}
+	getPromptLineCursor(lines = this.promptValue.split("\n")) {
+		let offset = 0;
+		for (let lineIndex = 0; lineIndex < lines.length; lineIndex += 1) {
+			const line = lines[lineIndex] ?? "";
+			const end = offset + line.length;
+			if (this.promptCursor <= end || lineIndex === lines.length - 1) return {
+				line: lineIndex,
+				column: Math.max(0, this.promptCursor - offset)
+			};
+			offset = end + 1;
+		}
+		return {
+			line: 0,
+			column: 0
+		};
+	}
+	getCurrentPromptLineStart() {
+		return this.promptValue.lastIndexOf("\n", Math.max(0, this.promptCursor - 1)) + 1;
+	}
+	getCurrentPromptLineEnd() {
+		const end = this.promptValue.indexOf("\n", this.promptCursor);
+		return end === -1 ? this.promptValue.length : end;
+	}
 	handleSlashSuggestionInput(data) {
 		const suggestions = this.getSlashSuggestions();
 		if (suggestions.length === 0) {
@@ -4802,19 +7016,19 @@ var ChatLayout = class {
 			this.completeSlashSuggestion(suggestions);
 			return true;
 		}
-		if (isEnterKey(data) && this.input.getValue().trim() !== suggestions[this.activeSlashSuggestionIndex]?.value) {
+		if (isEnterKey(data) && this.promptValue.trim() !== suggestions[this.activeSlashSuggestionIndex]?.value) {
 			this.completeSlashSuggestion(suggestions);
 			return true;
 		}
 		return false;
 	}
 	completeSlashSuggestion(suggestions) {
-		this.input.setValue(suggestions[this.activeSlashSuggestionIndex]?.value ?? this.input.getValue());
-		this.input.handleInput("\x1B[F");
+		this.promptValue = suggestions[this.activeSlashSuggestionIndex]?.value ?? this.promptValue;
+		this.promptCursor = this.promptValue.length;
 		this.promptHistory.resetBrowsing();
 	}
 	getSlashSuggestions() {
-		return getSlashCommandSuggestions(this.input.getValue());
+		return getSlashCommandSuggestions(this.promptValue);
 	}
 	getActiveModal() {
 		return this.messages[this.getActiveModalIndex()];
@@ -4827,6 +7041,7 @@ var ChatLayout = class {
 		this.submitUserInput(message);
 	}
 	submitUserInput(message) {
+		this.setTaskPlanNotice(void 0);
 		this.promptHistory.add(message);
 		if (message.startsWith("/")) this.submitCommand?.(message);
 		else this.submitMessage?.(message);
@@ -4835,8 +7050,15 @@ var ChatLayout = class {
 function colorUserMessageBorder(line) {
 	return line.replace("▌", ui.modelInline("▌"));
 }
-function renderInputWithoutPrompt(input, width) {
-	return (input.render(width + 2)[0] ?? "").replace(/^> /, "");
+function padPromptInputLine(line, width) {
+	return `${line}${" ".repeat(Math.max(0, width - stripAnsi(line).length))}`;
+}
+function isPrintableInput(data) {
+	if (data.length === 0) return false;
+	return [...data].every((char) => {
+		const code = char.charCodeAt(0);
+		return code >= 32 && code !== 127 && (code < 128 || code > 159);
+	});
 }
 //#endregion
 //#region src/agent/conversation.ts
@@ -4848,58 +7070,6 @@ function buildConversationPrompt(turns, latestMessage) {
 	return lines.join("\n\n");
 }
 //#endregion
-//#region src/agent/events.ts
-const agentEvent = {
-	status(status) {
-		return {
-			type: "status",
-			status
-		};
-	},
-	systemMessage(text) {
-		return {
-			type: "message",
-			role: "system",
-			text
-		};
-	},
-	assistantMessage(text, meta) {
-		return meta === void 0 ? {
-			type: "message",
-			role: "assistant",
-			text
-		} : {
-			type: "message",
-			role: "assistant",
-			text,
-			meta
-		};
-	},
-	toolCall(call, label) {
-		return {
-			type: "tool_call",
-			call,
-			label
-		};
-	},
-	knowledgeStatus(status, guidance) {
-		return guidance === void 0 ? {
-			type: "knowledge_status",
-			status
-		} : {
-			type: "knowledge_status",
-			status,
-			guidance
-		};
-	},
-	choice(options) {
-		return {
-			type: "choice",
-			...options
-		};
-	}
-};
-//#endregion
 //#region src/agent/health.ts
 async function checkAgentReady(modelGateway, abortSignal) {
 	const abortController = new AbortController();
@@ -4932,20 +7102,25 @@ function isAbortError(error) {
 //#endregion
 //#region src/agent/tools/executor.ts
 async function executeToolCall(workspaceRoot, call, options = {}) {
-	const definition = getToolDefinition(call.tool);
 	const startedAt = Date.now();
 	const context = {
 		workspaceRoot,
 		pathEnv: options.pathEnv,
-		logger: options.logger
+		logger: options.logger,
+		taskPlan: options.taskPlan
 	};
-	options.logger?.debug({
-		event: "tool_call",
-		tool: call.tool,
-		args: summarizeToolArgs(call)
-	}, "tool call");
 	try {
-		const result = await definition.execute(context, call.args);
+		const definition = getToolDefinition(call.tool);
+		const parsedCall = {
+			...call,
+			args: definition.argsSchema.parse(call.args)
+		};
+		options.logger?.debug({
+			event: "tool_call",
+			tool: parsedCall.tool,
+			args: summarizeToolArgs(parsedCall)
+		}, "tool call");
+		const result = await definition.execute(context, parsedCall.args);
 		const durationMs = Date.now() - startedAt;
 		options.logger?.debug({
 			event: "tool_result",
@@ -4965,26 +7140,56 @@ async function executeToolCall(workspaceRoot, call, options = {}) {
 		}, "tool result content");
 		return result;
 	} catch (error) {
-		options.logger?.error({
-			event: "tool_error",
+		const message = formatErrorMessage(error);
+		const logPayload = {
+			event: "tool_result",
 			tool: call.tool,
 			durationMs: Date.now() - startedAt,
+			error: message,
 			err: error
-		}, "tool failed");
-		throw error;
+		};
+		if (typeof options.logger?.warn === "function") options.logger.warn(logPayload, "tool returned error");
+		else options.logger?.debug(logPayload, "tool returned error");
+		return {
+			tool: call.tool,
+			content: `Tool ${call.tool} failed: ${message}`,
+			error: message,
+			warning: message
+		};
 	}
 }
 function summarizeToolArgs(call) {
+	if (call.tool === "plan_todo") {
+		const activeItem = call.args.items.find((item) => item.status === "in_progress")?.text;
+		return {
+			itemCount: call.args.items.length,
+			activeItem,
+			completedCount: call.args.items.filter((item) => item.status === "completed").length
+		};
+	}
+	if (call.tool === "write_file") return {
+		path: call.args.path,
+		contentLength: call.args.content.length,
+		lineCount: countLogicalLines(call.args.content),
+		createParentDirs: Boolean(call.args.create_parent_dirs),
+		overwrite: Boolean(call.args.overwrite),
+		expectedCurrentHashProvided: Boolean(call.args.expected_current_hash)
+	};
 	if (call.tool !== "edit_file") return call.args;
 	return {
 		path: call.args.path,
 		editCount: call.args.edits.length,
 		oldTextLengths: call.args.edits.map((edit) => edit.old_text.length),
 		newTextLengths: call.args.edits.map((edit) => edit.new_text.length),
-		expectedHashProvided: Boolean(call.args.expected_hash)
+		expectedCurrentHashProvided: Boolean(call.args.expected_current_hash)
 	};
 }
 function summarizeToolResult(result) {
+	if (result.tool === "plan_todo") return {
+		itemCount: result.plan.items.length,
+		activeItem: result.currentItem,
+		completedCount: result.completedCount
+	};
 	if (result.tool === "inspect_command") return {
 		cwd: result.cwd,
 		exitCode: result.exitCode,
@@ -4994,6 +7199,50 @@ function summarizeToolResult(result) {
 		stdoutLength: result.stdout.length,
 		stderrLength: result.stderr.length
 	};
+	if (result.tool === "git_status") return {
+		repoRoot: result.repoRoot,
+		branch: result.branch,
+		head: result.head,
+		hasHead: result.hasHead,
+		clean: result.clean,
+		fileCount: result.files.length,
+		truncated: result.truncated
+	};
+	if (result.tool === "git_diff") return {
+		repoRoot: result.repoRoot,
+		scope: result.scope,
+		path: result.path,
+		fileCount: result.fileCount,
+		truncated: result.truncated
+	};
+	if (result.tool === "git_log") return {
+		repoRoot: result.repoRoot,
+		commitCount: result.commits.length,
+		truncated: result.truncated
+	};
+	if (result.tool === "git_add") return {
+		repoRoot: result.repoRoot,
+		stagedPathCount: result.stagedPaths.length,
+		postStatusFileCount: result.files.length
+	};
+	if (result.tool === "git_commit") return {
+		repoRoot: result.repoRoot,
+		commit: result.commit.shortSha,
+		stagedPathCount: result.stagedPaths.length,
+		remainingFileCount: result.remainingFiles.length,
+		statLength: result.stat.length,
+		nameStatusLength: result.nameStatus.length
+	};
+	if (result.tool === "write_file") return {
+		hash: result.hash,
+		bytesWritten: result.bytesWritten,
+		lineCount: result.lineCount,
+		bytesChanged: result.bytesChanged,
+		lineDelta: result.lineDelta,
+		createdParentDirs: result.createdParentDirs,
+		kbState: result.kbState,
+		writeEvent: result.writeEvent
+	};
 	if (result.tool !== "edit_file") return {};
 	return {
 		beforeHash: result.beforeHash,
@@ -5004,6 +7253,14 @@ function summarizeToolResult(result) {
 		editEvent: result.editEvent
 	};
 }
+function countLogicalLines(content) {
+	if (content.length === 0) return 0;
+	const withoutTrailingLineEnding = content.replace(/\r?\n$/u, "");
+	return withoutTrailingLineEnding.length === 0 ? 1 : withoutTrailingLineEnding.split(/\r?\n/u).length;
+}
+function formatErrorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
 //#endregion
 //#region src/agent/prompts.ts
 function getChatSystemPrompt() {
@@ -5027,13 +7284,25 @@ function getChatSystemPrompt() {
 		"",
 		"Tool use:",
 		"- When using a tool, output exactly one tool JSON object and no prose, markdown, or additional JSON. After the tool result, either output the next single tool JSON object or a final plain-text answer.",
+		"- You already have permission to use the available tools to handle the user's request. Do not ask the user to provide tool results or permission to use an available tool.",
+		"- Do not claim to have read, created, edited, staged, committed, or run anything unless a tool result in this turn confirms it.",
+		"- Use plan_todo for non-trivial multi-step work before the first substantive repository tool call.",
+		"- Keep plan_todo items short, user-safe, and usually 2 to 6 items. Maintain exactly one in_progress item while work remains, update it after major progress changes, and clear it only when abandoning the plan or when no visible plan is useful.",
+		"- Do not use plan_todo for simple one-step answers, tiny reads, or trivial edits.",
 		"- Use read/search tools when the user asks about files, code, symbols, usages, tests, or project behavior.",
 		"- Use find_file for path or filename lookup. Use grep for text inside files. If grep output mentions another path, treat that mentioned path as content until find_file or read_file confirms it exists.",
 		"- Use list_files, grep, find_file, and read_file for exact file listing, search, lookup, and reading tasks.",
+		"- Use git_status, git_diff, and git_log for Git state, diffs, and history. Prefer these over inspect_command for Git workflow inspection.",
+		"- Use git_add and git_commit only when the user explicitly asks to stage or commit. Never stage unrelated files, never stage '.', and never commit unless staged paths exactly match the user's request.",
 		"- Use inspect_command only for quick read-only repo orientation when a short familiar command chain is clearer than several dedicated tool calls.",
 		"- inspect_command is not a shell. Unsafe commands, shell expansion, scripts, installs, builds, tests, network access, and file mutation are not available through it.",
 		"- Use read_file before editing a file so your edit is based on current file content and hash metadata.",
+		"- When passing expected_current_hash to edit_file or write_file, use the current pre-edit/pre-write hash from the latest read_file result for that exact file. Never invent it and never use a predicted after-edit or after-write hash.",
 		"- Use edit_file for targeted edits to existing files. Make multiple disjoint edits for the same file in one call when possible.",
+		"- Use write_file to create new files by default. It fails when the file already exists unless you are replacing the whole file with overwrite:true and expected_current_hash from read_file.",
+		"- When the user asks you to create a new file, call write_file. Do not answer that the file was created until write_file succeeds.",
+		"- Pass write_file create_parent_dirs:true only when the user intent clearly includes creating that folder path.",
+		"- Do not use inspect_command for file creation or file mutation.",
 		"- Keep edit_file old_text small but unique. Do not include line labels or grep prefixes in old_text; use exact file text only.",
 		"- Use edit/write tools when they are available and the user asks you to implement, fix, add, update, or refactor code.",
 		"- Use command/test tools when they are available and you need to inspect the environment, run tests, format, lint, typecheck, or verify behavior.",
@@ -5043,34 +7312,83 @@ function getChatSystemPrompt() {
 }
 //#endregion
 //#region src/agent/runtime.ts
-const MAX_TOOL_CALLS_PER_TURN = 8;
+const MAX_TOOL_CALLS_PER_TURN = 75;
 var TopchesterAgentRuntime = class {
 	context;
+	taskPlan = createTaskPlanController();
+	/**
+	* Holds the shared application context for one runtime instance.
+	* The runtime does not own those dependencies; it coordinates the
+	* workspace, model gateway, logger, config, and task-plan state that
+	* are passed in by the CLI or TUI layer.
+	*/
 	constructor(context) {
 		this.context = context;
 	}
+	/**
+	* Performs the lightweight startup model check used by the interactive
+	* agent before accepting work. The check is intentionally non-blocking
+	* from the user's point of view: timeout and failure both produce a
+	* visible status message, but the runtime still moves to ready so the
+	* user can continue.
+	*/
 	async checkAgent(abortSignal) {
 		const result = await checkAgentReady(this.context.modelGateway, abortSignal);
 		if (result === "ready") return [agentEvent.status("ready")];
 		if (result === "timed-out") return [agentEvent.systemMessage("Agent is taking a while, so I skipped the startup check."), agentEvent.status("ready")];
 		return [agentEvent.systemMessage("Agent did not say it was ready."), agentEvent.status("ready")];
 	}
+	/**
+	* Builds the initial knowledge-base status events shown by the TUI.
+	* This wraps the raw filesystem status with the same non-clean file count
+	* used by `/kb status`, so startup messaging reflects whether project
+	* knowledge is ready, missing, stale, or waiting for a sync.
+	*/
 	async checkKnowledgeBase() {
 		return getKnowledgeStatusEvents(await this.getKnowledgeStatusWithNonCleanFileCount());
 	}
-	async submitMessage(conversation, message, abortSignal) {
-		const prompt = buildConversationPrompt(conversation, message);
+	/**
+	* Runs one user chat turn through the agent loop. It builds the model
+	* prompt with relevant KB context, calls the model, executes any requested
+	* tools, feeds tool results back into the next prompt, and repeats until
+	* the model returns a normal assistant message or the loop hits its safety
+	* limit.
+	*
+	* Events are accumulated for the caller and optionally streamed through
+	* `onEvent` as soon as tool calls, task-plan updates, choices, or final
+	* messages are available. The method also enforces visible task-plan
+	* closure before a final answer when the model leaves an open plan.
+	*/
+	async submitMessage(conversation, message, abortSignal, onEvent) {
+		const prompt = await this.buildPromptWithKnowledgeContext(buildConversationPrompt(conversation, message), message);
 		const events = [];
+		const emit = async (...nextEvents) => {
+			events.push(...nextEvents);
+			if (!onEvent) return;
+			for (const event of nextEvents) await onEvent(event);
+		};
 		let nextPrompt = prompt;
 		let totalDurationMs = 0;
 		let lastModelId = "model";
 		let afterTool;
 		let toolProtocolOverride = readToolProtocolEnvOverride();
+		let requestedPlanClosure = false;
 		for (let toolCalls = 0; toolCalls <= MAX_TOOL_CALLS_PER_TURN; toolCalls += 1) {
 			const startedAt = Date.now();
+			const system = getChatSystemPrompt();
+			this.context.logger.debug({
+				event: "model_prompt",
+				purpose: "agent.primary",
+				afterTool,
+				toolProtocol: toolProtocolOverride,
+				promptLength: nextPrompt.length,
+				systemLength: system.length,
+				prompt: nextPrompt,
+				system
+			}, afterTool ? "model prompt after tool" : "model prompt");
 			const result = await generateAgentStep(this.context, {
 				purpose: "agent.primary",
-				system: getChatSystemPrompt(),
+				system,
 				prompt: nextPrompt,
 				abortSignal,
 				toolProtocol: toolProtocolOverride
@@ -5086,6 +7404,11 @@ var TopchesterAgentRuntime = class {
 				durationMs,
 				totalDurationMs,
 				textLength: result.text.length,
+				usage: result.usage,
+				inputTokens: result.usage?.inputTokens,
+				outputTokens: result.usage?.outputTokens,
+				totalTokens: result.usage?.totalTokens,
+				costUsd: result.usage?.costUsd,
 				hasToolCall: Boolean(toolCall),
 				toolProtocol: result.toolProtocol,
 				protocolAttempts: result.protocolAttempts,
@@ -5106,25 +7429,45 @@ var TopchesterAgentRuntime = class {
 			if (result.providerRejectedTools && result.toolProtocol === "text-json") toolProtocolOverride = "text-json";
 			else if (result.providerRejectedTools && result.toolProtocol === "text-xml") toolProtocolOverride = "text-xml";
 			if (!toolCall) {
-				events.push(agentEvent.assistantMessage(result.text.trim() || "I got an empty response from the model.", formatAgentMessageMeta(result.modelId, totalDurationMs)), agentEvent.status("ready"));
+				if (hasOpenTaskPlan(this.taskPlan.get())) {
+					if (!requestedPlanClosure) {
+						requestedPlanClosure = true;
+						nextPrompt = `${nextPrompt}\n\n${formatOpenPlanClosureInstruction(result.text, result.toolProtocol)}`;
+						continue;
+					}
+					await emit(agentEvent.taskPlan(this.taskPlan.update({ items: [] })));
+				}
+				await emit(agentEvent.assistantMessage(result.text.trim() || "I got an empty response from the model.", formatAgentMessageMeta(result.modelId, totalDurationMs)), agentEvent.status("ready"));
 				return events;
 			}
 			if (toolCalls === MAX_TOOL_CALLS_PER_TURN) {
-				events.push(agentEvent.systemMessage(`Stopped after ${MAX_TOOL_CALLS_PER_TURN} tool calls in one turn.`), agentEvent.status("ready"));
+				await emit(agentEvent.choice({
+					tone: "warning",
+					title: "Tool call limit reached",
+					body: `Stopped after ${MAX_TOOL_CALLS_PER_TURN} tool calls in one turn. Continue starts another turn; abort leaves the call stopped.`,
+					actions: [choiceAction("Continue", "Continue the previous task from where you stopped."), choiceAction("Abort", ABORT_CHOICE_VALUE)]
+				}), agentEvent.status("ready"));
 				return events;
 			}
 			const executableToolCall = toolCall;
-			const toolResult = await executeToolCall(this.context.workspaceRoot, executableToolCall, { logger: this.context.logger });
-			events.push(agentEvent.toolCall(executableToolCall, formatToolCallMessage(executableToolCall, toolResult)));
+			const toolResult = await executeToolCall(this.context.workspaceRoot, executableToolCall, {
+				logger: this.context.logger,
+				taskPlan: this.taskPlan
+			});
+			await emit(agentEvent.toolCall(executableToolCall, formatToolCallMessage(executableToolCall, toolResult)));
+			if (!isToolErrorResult(toolResult) && toolResult.tool === "plan_todo") await emit(agentEvent.taskPlan(toolResult.plan));
 			afterTool = executableToolCall.tool;
-			nextPrompt = `${nextPrompt}\n\n${formatToolResultForPrompt(toolResult)}\n\n${formatContinuationInstruction(result.toolProtocol)}`;
+			nextPrompt = `${nextPrompt}\n\n${formatToolResultForPrompt(toolResult)}\n\n${formatContinuationInstruction(result.toolProtocol, toolResult)}`;
 		}
-		return [
-			...events,
-			agentEvent.assistantMessage("I stopped because the tool loop ended unexpectedly.", formatAgentMessageMeta(lastModelId, totalDurationMs)),
-			agentEvent.status("ready")
-		];
+		await emit(agentEvent.assistantMessage("I stopped because the tool loop ended unexpectedly.", formatAgentMessageMeta(lastModelId, totalDurationMs)), agentEvent.status("ready"));
+		return events;
 	}
+	/**
+	* Executes a slash command through the shared command dispatcher and maps
+	* the command output into runtime events. Commands that can change KB
+	* readiness also refresh the displayed knowledge status so the TUI footer
+	* and chat status stay aligned with the command result.
+	*/
 	async submitSlashCommand(command, onProgress) {
 		const result = await executeSlashCommand(command, {
 			workspaceRoot: this.context.workspaceRoot,
@@ -5138,6 +7481,12 @@ var TopchesterAgentRuntime = class {
 		events.push(agentEvent.status("ready"));
 		return events;
 	}
+	/**
+	* Reads the project KB status and augments it with a count of files that
+	* would be touched by a dry-run compile. The dry run is only performed for
+	* a ready KB directory, because missing or incomplete KB states already
+	* have enough information for the startup and status messages.
+	*/
 	async getKnowledgeStatusWithNonCleanFileCount() {
 		const status = getKnowledgeStatus(this.context.workspaceRoot);
 		if (!status.kbExists || !status.kbIsDirectory || status.kbContentState !== "ready") return status;
@@ -5147,7 +7496,50 @@ var TopchesterAgentRuntime = class {
 			nonCleanFileCount: result.files.length
 		};
 	}
+	/**
+	* Adds relevant L1 knowledge context to the conversation prompt when the
+	* compiled KB is present and ready. Search failures are logged and then
+	* ignored on purpose: stale or broken KB search should not prevent the
+	* user's chat turn from reaching the model.
+	*/
+	async buildPromptWithKnowledgeContext(prompt, message) {
+		const status = getKnowledgeStatus(this.context.workspaceRoot);
+		if (!status.kbExists || !status.kbIsDirectory || status.kbContentState !== "ready") return prompt;
+		try {
+			const contextPack = await createL1ContextPack(this.context.workspaceRoot, message, {
+				limit: 8,
+				minScore: 12
+			});
+			this.context.logger.debug({
+				event: "kb_context_pack",
+				query: message,
+				entryCount: contextPack.entryCount,
+				relevantFileCount: contextPack.relevantFiles.length,
+				paths: contextPack.relevantFiles.map((file) => file.path),
+				warnings: contextPack.warnings
+			}, "kb context pack");
+			this.context.logger.trace({
+				event: "kb_context_pack_payload",
+				contextPack
+			}, "kb context pack payload");
+			if (contextPack.relevantFiles.length === 0) return prompt;
+			return `${formatL1ContextPackForPrompt(contextPack)}\n\nConversation:\n${prompt}`;
+		} catch (error) {
+			this.context.logger.debug({
+				event: "kb_context_pack_failed",
+				error: error instanceof Error ? error.message : String(error)
+			}, "kb context pack failed");
+			return prompt;
+		}
+	}
 };
+/**
+* Calls the configured model gateway for a single agent step and normalizes
+* the result into the newer `ModelAgentResult` shape. Gateways that implement
+* native agent stepping receive the tool registry directly; older text-only
+* gateways fall back to parsing a JSON or XML tool call out of the model text
+* so the rest of the runtime can use the same tool loop.
+*/
 async function generateAgentStep(context, request) {
 	if ("generateAgentStep" in context.modelGateway && typeof context.modelGateway.generateAgentStep === "function") return context.modelGateway.generateAgentStep({
 		...request,
@@ -5176,15 +7568,33 @@ async function generateAgentStep(context, request) {
 		openRouterRoutingApplied: false
 	};
 }
+/**
+* Reads the optional environment override for the tool-calling protocol.
+* Invalid values are ignored instead of failing startup, which keeps local
+* experimentation contained to supported protocol names while preserving the
+* normal automatic negotiation path by default.
+*/
 function readToolProtocolEnvOverride() {
 	const value = process.env.TOPCHESTER_TOOL_PROTOCOL;
 	if (value === "auto" || value === "native" || value === "text-json" || value === "text-xml") return value;
 }
+/**
+* Applies TUI styling to per-file KB sync states. The raw scanner statuses
+* are preserved as text, but success, warning, and error categories get
+* different colors so slash-command output is readable without changing the
+* underlying command semantics.
+*/
 function formatTuiSyncStatus(status) {
 	if (status === "current") return ui.ok(status);
 	if (status === "invalid" || status === "missing_file") return ui.error(status);
 	return ui.warn(status);
 }
+/**
+* Decides whether a slash command should trigger a fresh KB status event.
+* Only KB subcommands that can initialize, rebuild, sync, reset, or inspect
+* the compiled knowledge state need the refresh; other commands can return
+* their output without doing extra filesystem work.
+*/
 function shouldRefreshKnowledgeStatus(command) {
 	const parsed = parseSlashCommand(command);
 	return parsed?.name === "kb" && [
@@ -5195,19 +7605,44 @@ function shouldRefreshKnowledgeStatus(command) {
 		"status"
 	].includes(parsed.args[0] ?? "");
 }
+/**
+* Converts a computed KB status into the startup event shape consumed by the
+* TUI. The event carries both the structured status and a short next-step
+* message, letting renderers show precise state while keeping user-facing
+* guidance in one place.
+*/
 function getKnowledgeStatusEvents(status) {
 	return [agentEvent.knowledgeStatus(status, formatStartupKnowledgeGuidance(status))];
 }
+/**
+* Produces the short guidance line shown with startup KB status. The message
+* is deliberately action-oriented: it points to the next command that would
+* fix the current state and returns nothing when the KB is ready and clean.
+*/
 function formatStartupKnowledgeGuidance(status) {
 	if (!status.kbExists) return "Next: run /kb init, then /kb compile to create project knowledge.";
 	if (!status.kbIsDirectory) return "Fix the KB path or config, then run /kb status.";
 	if (status.kbContentState !== "ready") return "Next: run /kb compile to build project knowledge.";
 	if ((status.nonCleanFileCount ?? 0) > 0) return "Next: run /kb sync to update project knowledge, or /kb status to inspect the files.";
 }
+/**
+* Serializes a tool execution result into the text that is fed back to the
+* model after a tool call. Each tool gets the metadata the model needs for
+* the next step, such as file hashes, diffs, command exit status, truncation
+* state, or KB dirty-state signals, while errors are presented in a uniform
+* error block.
+*/
 function formatToolResultForPrompt(result) {
 	const path = result.path ? ` ${JSON.stringify(result.path)}` : "";
 	const command = result.command ? ` via ${result.command}` : "";
 	const warning = result.warning ? `\nWarning: ${result.warning}` : "";
+	if (isToolErrorResult(result)) return [
+		`Tool result from ${result.tool}${path}${command}:`,
+		`Error: ${result.error}`,
+		"```",
+		result.content,
+		"```"
+	].join("\n");
 	if (result.tool === "read_file") return [
 		`Tool result from ${result.tool}${path}${command}:${warning}`,
 		`hash: ${result.hash}`,
@@ -5215,6 +7650,7 @@ function formatToolResultForPrompt(result) {
 		result.content,
 		"```"
 	].join("\n");
+	if (result.tool === "plan_todo") return [`Tool result from ${result.tool}:`, result.content].join("\n");
 	if (result.tool === "edit_file") return [
 		`Tool result from ${result.tool}${path}:`,
 		`before_hash: ${result.beforeHash}`,
@@ -5226,6 +7662,18 @@ function formatToolResultForPrompt(result) {
 		result.diff,
 		"```"
 	].join("\n");
+	if (result.tool === "write_file") return [
+		`Tool result from ${result.tool}${path}:`,
+		result.beforeHash ? `before_hash: ${result.beforeHash}` : "",
+		`after_hash: ${result.hash}`,
+		`bytes_written: ${result.bytesWritten}`,
+		result.bytesChanged !== void 0 ? `bytes_changed: ${result.bytesChanged}` : "",
+		`line_count: ${result.lineCount}`,
+		result.lineDelta !== void 0 ? `line_delta: ${result.lineDelta}` : "",
+		`kb_state: ${result.kbState}`,
+		result.createdParentDirs.length > 0 ? `created_parent_dirs: ${result.createdParentDirs.join(", ")}` : "",
+		`summary: ${result.writeEvent.writeSummary}`
+	].filter(Boolean).join("\n");
 	if (result.tool === "inspect_command") return [
 		`Tool result from ${result.tool} via ${result.command}:`,
 		`cwd: ${result.cwd}`,
@@ -5238,6 +7686,61 @@ function formatToolResultForPrompt(result) {
 		result.content,
 		"```"
 	].filter(Boolean).join("\n");
+	if (result.tool === "git_status") return [
+		`Tool result from ${result.tool}${path}:`,
+		`repo_root: ${result.repoRoot ?? "(none)"}`,
+		`branch: ${result.branch ?? "(detached)"}`,
+		`head: ${result.head ?? "(none)"}`,
+		`has_head: ${result.hasHead}`,
+		`clean: ${result.clean}`,
+		`changed_file_count: ${result.files.length}`,
+		`truncated: ${result.truncated}`,
+		warning ? warning.trimStart() : "",
+		"```",
+		result.content,
+		"```"
+	].filter(Boolean).join("\n");
+	if (result.tool === "git_diff") return [
+		`Tool result from ${result.tool}${path}:`,
+		`repo_root: ${result.repoRoot ?? "(none)"}`,
+		`scope: ${result.scope}`,
+		`path: ${result.path ?? "(all)"}`,
+		`file_count: ${result.fileCount}`,
+		`truncated: ${result.truncated}`,
+		warning ? warning.trimStart() : "",
+		"```diff",
+		result.content,
+		"```"
+	].filter(Boolean).join("\n");
+	if (result.tool === "git_log") return [
+		`Tool result from ${result.tool}${path}:`,
+		`repo_root: ${result.repoRoot ?? "(none)"}`,
+		`commit_count: ${result.commits.length}`,
+		`truncated: ${result.truncated}`,
+		warning ? warning.trimStart() : "",
+		"```",
+		result.content,
+		"```"
+	].filter(Boolean).join("\n");
+	if (result.tool === "git_add") return [
+		`Tool result from ${result.tool}:`,
+		`repo_root: ${result.repoRoot ?? "(none)"}`,
+		`staged_paths: ${result.stagedPaths.join(", ")}`,
+		warning ? warning.trimStart() : "",
+		"```",
+		result.content,
+		"```"
+	].filter(Boolean).join("\n");
+	if (result.tool === "git_commit") return [
+		`Tool result from ${result.tool}:`,
+		`repo_root: ${result.repoRoot ?? "(none)"}`,
+		`commit: ${result.commit.shortSha} ${result.commit.subject}`,
+		`staged_paths: ${result.stagedPaths.join(", ")}`,
+		`remaining_changed_file_count: ${result.remainingFiles.length}`,
+		"```",
+		result.content,
+		"```"
+	].join("\n");
 	return [
 		`Tool result from ${result.tool}${path}${command}:${warning}`,
 		"```",
@@ -5245,26 +7748,105 @@ function formatToolResultForPrompt(result) {
 		"```"
 	].join("\n");
 }
-function formatContinuationInstruction(protocol) {
-	return `Continue the user's request using the tool result above. ${protocol === "text-xml" ? "If another tool is needed, reply with only one XML tool call." : protocol === "text-json" ? "If another tool is needed, reply with only that tool JSON." : "If another tool is needed, use the available tool calling path."} Otherwise answer the user. Do not guess.`;
+/**
+* Builds the follow-up instruction appended after each tool result. It keeps
+* the model on the active task, reminds it to maintain the visible plan, and
+* restates the current tool-call protocol so the next model step remains
+* parseable by the runtime.
+*/
+function formatContinuationInstruction(protocol, result) {
+	const toolInstruction = protocol === "text-xml" ? "If another tool is needed, reply with only one XML tool call." : protocol === "text-json" ? "If another tool is needed, reply with only that tool JSON." : "If another tool is needed, use the available tool calling path.";
+	return [
+		"Continue the user's request using the tool result above and the visible plan when one is active.",
+		result.tool === "find_file" ? "find_file results are paths only; if the user asked to read or answer from file contents, call read_file on the relevant path before answering. Do not ask the user to provide the read_file result or permission." : "",
+		"Update plan_todo after major progress changes.",
+		"Before a final answer, close the visible plan by calling plan_todo with all finished items marked completed, or with [] if abandoning the plan.",
+		toolInstruction,
+		"Otherwise answer the user. Do not guess."
+	].filter(Boolean).join(" ");
+}
+/**
+* Creates the corrective prompt used when the model tries to answer while a
+* visible task plan is still open. The draft final answer is preserved so the
+* model can reuse it after closing the plan, but the immediate instruction is
+* to call `plan_todo` first.
+*/
+function formatOpenPlanClosureInstruction(draftAnswer, protocol) {
+	const toolInstruction = protocol === "text-xml" ? "Reply now with only one XML plan_todo tool call." : protocol === "text-json" ? "Reply now with only the plan_todo JSON object." : "Use the available tool calling path now to call plan_todo.";
+	const trimmedDraft = draftAnswer.trim();
+	return [
+		"The visible plan still has unfinished items, so do not provide the final answer yet.",
+		"First close the plan with plan_todo: mark completed work as completed, keep one item in_progress only if work truly remains, or use [] if abandoning the plan.",
+		toolInstruction,
+		trimmedDraft ? `After the plan_todo result, use this draft final answer if it is still accurate:\n${trimmedDraft}` : ""
+	].filter(Boolean).join("\n");
 }
+/**
+* Formats a compact, user-visible summary for a tool call event. When a
+* result is available the summary includes useful completion details, such as
+* changed-line counts, staged paths, commit subjects, or command failures,
+* instead of echoing the full tool payload.
+*/
 function formatToolCallMessage(call, result) {
+	if (result && isToolErrorResult(result)) return `${call.tool} failed: ${result.error}`;
 	switch (call.tool) {
+		case "plan_todo": return result?.tool === "plan_todo" ? `plan_todo: ${result.plan.items.length} items, ${result.inProgressCount} active` : `plan_todo: ${call.args.items.length} items`;
 		case "read_file": return `read_file: ${call.args.path}`;
 		case "list_files": return `list_files: ${call.args.path}${call.args.recursive ? " (recursive)" : ""}`;
 		case "grep": return `grep: ${call.args.pattern} in ${call.args.path ?? "."}`;
 		case "find_file": return `find_file: ${call.args.query} in ${call.args.path}`;
 		case "edit_file": return `edit_file: ${call.args.path}${formatEditFileChangeSummary(result)}`;
+		case "write_file": return `write_file: ${call.args.path}${formatWriteFileChangeSummary(result)}`;
+		case "git_status": return `git_status: ${result?.tool === "git_status" ? `${result.files.length} changed` : call.args.path}`;
+		case "git_diff": return `git_diff: ${formatGitDiffCallSummary(call, result)}`;
+		case "git_log": return `git_log: ${result?.tool === "git_log" ? `${result.commits.length} commits` : `${call.args.limit} commits`}`;
+		case "git_add": return `git_add: ${result?.tool === "git_add" ? `${result.stagedPaths.length} files staged` : `${call.args.paths.length} files`}`;
+		case "git_commit": return `git_commit: ${result?.tool === "git_commit" ? `${result.commit.shortSha} ${result.commit.subject}` : call.args.message}`;
 		case "inspect_command": return `inspect_command: ${call.args.command}`;
 	}
 }
+/**
+* Summarizes a `git_diff` call for the TUI event list. Successful results
+* report the resolved scope, file count, and truncation marker; pending or
+* failed calls fall back to the requested scope from the tool arguments.
+*/
+function formatGitDiffCallSummary(call, result) {
+	if (result?.tool === "git_diff" && !isToolErrorResult(result)) return `${result.scope} (${result.fileCount} files${result.truncated ? ", truncated" : ""})`;
+	return call.args.scope;
+}
+/**
+* Returns the parenthesized change summary for a successful `edit_file`
+* result. Non-edit results and failed edits intentionally return an empty
+* suffix so the main tool-call formatter can keep one path for success,
+* failure, and pre-result display.
+*/
 function formatEditFileChangeSummary(result) {
-	if (result?.tool !== "edit_file") return "";
+	if (result?.tool !== "edit_file" || isToolErrorResult(result)) return "";
 	return ` (changed ${result.editEvent.diffSummary})`;
 }
+/**
+* Returns the parenthesized write summary for a successful `write_file`
+* result. The helper mirrors the edit summary helper, keeping write-specific
+* result details out of the larger switch that formats all tool-call messages.
+*/
+function formatWriteFileChangeSummary(result) {
+	if (result?.tool !== "write_file" || isToolErrorResult(result)) return "";
+	return ` (${result.writeEvent.writeSummary})`;
+}
+/**
+* Formats the assistant-message metadata shown next to the final response.
+* The model identifier and cumulative turn duration are kept together here
+* so callers do not need to know how agent-loop timing should be presented.
+*/
 function formatAgentMessageMeta(model, durationMs) {
 	return `${model} · ${formatDuration$1(durationMs)}`;
 }
+/**
+* Converts elapsed milliseconds into the short human-readable duration used
+* in assistant metadata. Very short turns keep one decimal place, normal
+* sub-minute turns round to seconds, and longer turns switch to minutes plus
+* remaining seconds.
+*/
 function formatDuration$1(durationMs) {
 	const totalSeconds = Math.max(0, durationMs / 1e3);
 	if (totalSeconds < 10) return `${formatNumber(totalSeconds, 1)} sec`;
@@ -5274,6 +7856,12 @@ function formatDuration$1(durationMs) {
 	if (seconds === 0) return `${minutes} min`;
 	return `${minutes} min ${seconds} sec`;
 }
+/**
+* Formats a number with a fixed number of fraction digits using the English
+* locale expected by the TUI metadata strings. Keeping this tiny wrapper
+* avoids repeating the minimum and maximum fraction-digit options at every
+* call site.
+*/
 function formatNumber(value, fractionDigits) {
 	return value.toLocaleString("en", {
 		minimumFractionDigits: fractionDigits,
@@ -5285,7 +7873,7 @@ function formatNumber(value, fractionDigits) {
 function renderRuntimeEvent(event) {
 	switch (event.type) {
 		case "message": return [event.role === "assistant" ? agentMessage(event.text, event.meta) : systemMessage(event.text)];
-		case "tool_call": return [systemMessage(event.label)];
+		case "tool_call": return [toolCallMessage(event.call, event.label)];
 		case "knowledge_status": return [systemMessage([`KB status: ${formatKnowledgePathStatus(event.status)}${formatKbPathSource(event.status)}`, event.guidance].filter(Boolean).join("\n"))];
 		case "choice": return [modalMessage({
 			tone: event.tone,
@@ -5293,6 +7881,7 @@ function renderRuntimeEvent(event) {
 			body: event.body,
 			actions: event.actions
 		})];
+		case "task_plan": return [];
 		case "status": return [];
 	}
 }
@@ -5306,6 +7895,7 @@ var TopchesterTuiShell = class {
 	options;
 	runtime;
 	session;
+	taskPlanNoticeTimer;
 	constructor(context, runtime, options = {}) {
 		this.context = context;
 		this.options = options;
@@ -5322,7 +7912,7 @@ var TopchesterTuiShell = class {
 		const folderName = getFolderName(this.context.workspaceRoot);
 		const modelLabel = getModelLabel(this.context);
 		if (!process.stdin.isTTY || !process.stdout.isTTY) {
-			console.log(renderStaticLayout(messages, folderName, modelLabel));
+			console.log(renderStaticLayout(messages, folderName, modelLabel, this.options.initialTaskPlan));
 			return;
 		}
 		const terminal = new ProcessTerminal();
@@ -5341,6 +7931,7 @@ var TopchesterTuiShell = class {
 				process.exit(0);
 			}
 		});
+		app.setTaskPlan(this.options.initialTaskPlan);
 		app.setSubmitMessage((message) => {
 			this.submitChatMessage(app, tui, message);
 		});
@@ -5383,7 +7974,7 @@ var TopchesterTuiShell = class {
 		busy.start();
 		tui.requestRender();
 		try {
-			await this.applyRuntimeEvents(app, await this.runtime.checkAgent(abortController.signal));
+			await this.applyRuntimeEvents(app, await this.runtime.checkAgent(abortController.signal), tui);
 		} catch (error) {
 			if (cancelled) {
 				app.addMessage(systemMessage("Agent check stopped."));
@@ -5397,7 +7988,7 @@ var TopchesterTuiShell = class {
 			app.setCancelPending(void 0);
 			busy.stop();
 		}
-		if (app.isReady()) await this.applyRuntimeEvents(app, await this.runtime.checkKnowledgeBase());
+		if (app.isReady()) await this.applyRuntimeEvents(app, await this.runtime.checkKnowledgeBase(), tui);
 		tui.requestRender();
 	}
 	async submitChatMessage(app, tui, message) {
@@ -5419,12 +8010,16 @@ var TopchesterTuiShell = class {
 		busy.start();
 		tui.requestRender();
 		try {
+			await this.clearTaskPlanForNewTurn(app);
 			await this.persistPayloadWithWarning(app, {
 				kind: "message",
 				role: "user",
 				text: message
 			});
-			await this.applyRuntimeEvents(app, await this.runtime.submitMessage(app.getConversationTurns(), message, abortController.signal));
+			await this.runtime.submitMessage(app.getConversationTurns(), message, abortController.signal, async (event) => {
+				await this.applyRuntimeEvents(app, [event], tui);
+				tui.requestRender();
+			});
 		} catch (error) {
 			if (cancelled) {
 				app.addMessage(systemMessage("Response stopped."));
@@ -5454,10 +8049,11 @@ var TopchesterTuiShell = class {
 		busy.start();
 		tui.requestRender();
 		try {
+			await this.clearTaskPlanForNewTurn(app);
 			await this.persistPayloadWithWarning(app, slashCommandToSessionPayload(command));
 			await this.applyRuntimeEvents(app, await this.runtime.submitSlashCommand(command, (event) => {
 				busy.setActivity(event.message);
-			}));
+			}), tui);
 		} catch (error) {
 			const errorMessage = error instanceof Error ? error.message : String(error);
 			app.addMessage(systemMessage(`Command failed: ${errorMessage}`));
@@ -5471,14 +8067,41 @@ var TopchesterTuiShell = class {
 			tui.requestRender();
 		}
 	}
-	async applyRuntimeEvents(app, events) {
+	async applyRuntimeEvents(app, events, renderRequester) {
 		for (const event of events) {
 			if (event.type === "status") app.setStatus(event.status);
 			if (event.type === "knowledge_status") app.setKnowledgeStatus(event.status);
+			if (event.type === "task_plan") {
+				const change = app.setTaskPlan(event.plan);
+				app.setTaskPlanNotice(formatTaskPlanNotice(change, event.plan));
+				this.scheduleTaskPlanNoticeClear(app, renderRequester);
+			}
 			for (const message of renderRuntimeEvent(event)) app.addMessage(message);
 			await this.persistPayloadWithWarning(app, runtimeEventToSessionPayload(event));
 		}
 	}
+	scheduleTaskPlanNoticeClear(app, renderRequester) {
+		if (this.taskPlanNoticeTimer) {
+			clearTimeout(this.taskPlanNoticeTimer);
+			this.taskPlanNoticeTimer = void 0;
+		}
+		if (!renderRequester) return;
+		this.taskPlanNoticeTimer = setTimeout(() => {
+			this.taskPlanNoticeTimer = void 0;
+			app.setTaskPlanNotice(void 0);
+			renderRequester.requestRender();
+		}, 2500);
+		this.taskPlanNoticeTimer.unref?.();
+	}
+	async clearTaskPlanForNewTurn(app) {
+		const clearedPlan = app.clearTaskPlan();
+		if (!clearedPlan) return;
+		await this.persistPayloadWithWarning(app, {
+			kind: "task_plan",
+			items: clearedPlan.items,
+			updatedAt: clearedPlan.updatedAt
+		});
+	}
 	async persistPayloadWithWarning(app, payload) {
 		if (!this.session || !payload) return;
 		try {
@@ -5501,9 +8124,14 @@ async function persistMessagesWithWarning(session, messages, warningTarget = mes
 	}
 }
 function chatMessageToSessionPayload(message) {
-	if (message.kind === "system" || message.kind === "user" || message.kind === "agent") return {
+	if (message.kind === "system" || message.kind === "user") return {
+		kind: "message",
+		role: message.kind,
+		text: message.text
+	};
+	if (message.kind === "agent") return {
 		kind: "message",
-		role: message.kind === "agent" ? "assistant" : message.kind,
+		role: "assistant",
 		text: message.text,
 		...message.meta === void 0 ? {} : { meta: message.meta }
 	};
@@ -5514,6 +8142,11 @@ function chatMessageToSessionPayload(message) {
 		...message.body === void 0 ? {} : { body: message.body },
 		actions: message.actions
 	};
+	if (message.kind === "tool_call") return {
+		kind: "tool_call",
+		label: message.label,
+		call: message.call
+	};
 }
 function runtimeEventToSessionPayload(event) {
 	switch (event.type) {
@@ -5528,6 +8161,11 @@ function runtimeEventToSessionPayload(event) {
 			label: event.label,
 			call: event.call
 		};
+		case "task_plan": return {
+			kind: "task_plan",
+			items: event.plan.items,
+			updatedAt: event.plan.updatedAt
+		};
 		case "knowledge_status": return;
 		case "choice": return {
 			kind: "choice",
@@ -5738,16 +8376,19 @@ async function resolveRunSession(workspaceRoot, resume) {
 }
 async function loadConversation(workspaceRoot, resume) {
 	return rehydrateSession((await loadSession(workspaceRoot, resume)).events).messages.flatMap((message) => {
-		if (message.kind === "modal" || message.modelContext === false) return [];
-		if (message.kind === "user") return [{
-			role: "user",
-			text: message.text
-		}];
-		if (message.kind === "agent") return [{
-			role: "assistant",
-			text: message.text
-		}];
-		return [];
+		switch (message.kind) {
+			case "user": return message.modelContext === false ? [] : [{
+				role: "user",
+				text: message.text
+			}];
+			case "agent": return message.modelContext === false ? [] : [{
+				role: "assistant",
+				text: message.text
+			}];
+			case "system":
+			case "tool_call":
+			case "modal": return [];
+		}
 	});
 }
 async function persistStartupMessages(session, context) {
@@ -5773,7 +8414,14 @@ function printPlainEvent(event) {
 		console.log(event.label);
 		return;
 	}
-	if (event.type === "knowledge_status" && event.guidance) console.log(event.guidance);
+	if (event.type === "knowledge_status" && event.guidance) {
+		console.log(event.guidance);
+		return;
+	}
+	if (event.type === "task_plan") {
+		const notice = formatTaskPlanNotice("updated", event.plan);
+		if (notice) console.log(notice);
+	}
 }
 function pushJson(events, runId, sessionId, type, fields) {
 	events.push({
@@ -5805,9 +8453,12 @@ program.action(async () => {
 	try {
 		if (options.resume) {
 			const loaded = await loadSession(context.workspaceRoot, options.resume);
+			const session = await loadSessionForAppend(context.workspaceRoot, loaded.sessionId);
+			const rehydrated = rehydrateSession(loaded.events);
 			await new TopchesterTuiShell(context, void 0, {
-				session: await loadSessionForAppend(context.workspaceRoot, loaded.sessionId),
-				initialMessages: rehydrateSession(loaded.events).messages
+				session,
+				initialMessages: rehydrated.messages,
+				initialTaskPlan: rehydrated.taskPlan
 			}).render();
 			return;
 		}
@@ -5839,6 +8490,9 @@ program.command("run").description("run one prompt or slash command without open
 		process.exitCode = 1;
 	}
 });
+program.command("search").description("search compiled L1 knowledge entries").argument("<query...>", "search query").option("--limit <count>", "maximum number of matches", parsePositiveInteger).option("--json", "write full JSON search result to stdout").action(async (queryParts, options) => {
+	await executeKbSearchCommand(queryParts, options);
+});
 const kbCommand = program.command("kb").description("knowledge base commands");
 kbCommand.command("init").description("initialize a project knowledge base").action(async () => {
 	const context = createContextFromOptions();
@@ -5872,6 +8526,12 @@ kbCommand.command("sync").description("sync non-clean project files into the kno
 	console.log(formatKnowledgeSyncResult(result).join("\n"));
 	if (isPartialKnowledgeCompileResult(result)) process.exitCode = 2;
 });
+kbCommand.command("search").alias("query").description("search compiled L1 knowledge entries").argument("<query...>", "search query").option("--limit <count>", "maximum number of matches", parsePositiveInteger).option("--json", "write full JSON search result to stdout").action(async (queryParts, options) => {
+	await executeKbSearchCommand(queryParts, options);
+});
+kbCommand.command("context").description("create an L1 context pack for a query").argument("<query...>", "context query").option("--limit <count>", "maximum number of relevant files", parsePositiveInteger).option("--min-score <score>", "minimum match score", parseNonNegativeNumber).option("--json", "write JSON context pack to stdout").option("--full-l1", "include full raw L1 entries in JSON output").action(async (queryParts, options) => {
+	await executeKbContextCommand(queryParts, options);
+});
 kbCommand.command("reset").description("delete the local project knowledge base and cache").action(async () => {
 	const context = createContextFromOptions();
 	const result = await ui.progress("Resetting project knowledge base...", (report) => resetKnowledgeBase(context.workspaceRoot, { onProgress: (event) => report(event.message) }));
@@ -5918,6 +8578,31 @@ function createContextFromOptions() {
 		devFlags: options.dev
 	});
 }
+async function executeKbSearchCommand(queryParts, options) {
+	const context = createContextFromOptions();
+	const query = queryParts.join(" ");
+	const result = options.json ? await searchL1Knowledge(context.workspaceRoot, query, { limit: options.limit }) : await ui.spinner("Searching L1 knowledge entries...", () => searchL1Knowledge(context.workspaceRoot, query, { limit: options.limit }));
+	if (options.json) {
+		console.log(JSON.stringify(stripEmptyContainers(result), null, 2));
+		return;
+	}
+	console.log(formatL1KnowledgeSearchResult(result).join("\n"));
+}
+async function executeKbContextCommand(queryParts, options) {
+	const context = createContextFromOptions();
+	const query = queryParts.join(" ");
+	const contextPackOptions = {
+		limit: options.limit,
+		minScore: options.minScore,
+		includeFullL1: options.fullL1
+	};
+	const result = options.json ? await createL1ContextPack(context.workspaceRoot, query, contextPackOptions) : await ui.spinner("Creating L1 context pack...", () => createL1ContextPack(context.workspaceRoot, query, contextPackOptions));
+	if (options.json) {
+		console.log(JSON.stringify(stripEmptyContainers(result), null, 2));
+		return;
+	}
+	console.log(formatL1ContextPackResult(result).join("\n"));
+}
 function formatStartupError(error) {
 	const message = error instanceof Error ? error.message : String(error);
 	if (message.includes("Could not read session metadata") || message.includes("Could not read session event") || message.includes("ENOENT")) return message.includes("metadata.json") || message.includes("events.jsonl") ? message : "Session not found";
@@ -5931,6 +8616,11 @@ function parsePositiveInteger(value) {
 	if (!Number.isInteger(parsed) || parsed <= 0) throw new Error("Expected a positive integer.");
 	return parsed;
 }
+function parseNonNegativeNumber(value) {
+	const parsed = Number(value);
+	if (!Number.isFinite(parsed) || parsed < 0) throw new Error("Expected a non-negative number.");
+	return parsed;
+}
 function formatDryRunSyncStatus(status) {
 	if (status === "current") return ui.ok(status);
 	if (status === "invalid" || status === "missing_file") return ui.error(status);