topchester-ai 0.10.0 → 0.12.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) {
@@ -97,23 +97,26 @@ 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 })
 });
@@ -123,7 +126,7 @@ async function editWorkspaceFile(workspaceRoot, args, options = {}) {
 		const fileStat = await statExistingFile(scopedPath.path, args.path);
 		const beforeBytes = await readFile(scopedPath.path);
 		const beforeHash = hashBytes$1(beforeBytes);
-		if (args.expected_hash && args.expected_hash !== beforeHash) throw new Error(`edit_file expected_hash did not match ${scopedPath.relativePath}.`);
+		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$1(afterBytes);
@@ -376,9 +379,12 @@ 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,
+	parallelSafe: true,
+	mutatesWorkspace: false,
+	resourceKeys: (args) => [`find:${args.path}`],
 	execute: (context, args) => findWorkspaceFilesByName(context.workspaceRoot, args, {
 		pathEnv: context.pathEnv,
 		logger: context.logger
@@ -829,7 +835,7 @@ function parseGitLog(output) {
 		};
 	});
 }
-function truncateText(content, maxBytes) {
+function truncateText$1(content, maxBytes) {
 	if (Buffer.byteLength(content) <= maxBytes) return {
 		content,
 		truncated: false
@@ -915,6 +921,9 @@ const gitStatusTool = defineTool({
 	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,
+	parallelSafe: true,
+	mutatesWorkspace: false,
+	resourceKeys: (args) => [`git-status:${args.path}`],
 	execute: (context, args) => inspectGitStatus(context, args)
 });
 const gitDiffTool = defineTool({
@@ -922,6 +931,9 @@ const gitDiffTool = defineTool({
 	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,
+	parallelSafe: true,
+	mutatesWorkspace: false,
+	resourceKeys: (args) => [`git-diff:${args.path ?? "."}:${args.scope}`],
 	execute: (context, args) => inspectGitDiff(context, args)
 });
 const gitLogTool = defineTool({
@@ -929,6 +941,9 @@ const gitLogTool = defineTool({
 	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,
+	parallelSafe: true,
+	mutatesWorkspace: false,
+	resourceKeys: (args) => [`git-log:${args.path ?? "."}`],
 	execute: (context, args) => inspectGitLog(context, args)
 });
 const gitAddTool = defineTool({
@@ -1056,7 +1071,7 @@ async function inspectGitDiff(context, args) {
 			changedFiles.add(file);
 		}
 	}
-	const bounded = truncateText(sections.join("\n").trimEnd() || "No diff.", args.max_bytes);
+	const bounded = truncateText$1(sections.join("\n").trimEnd() || "No diff.", args.max_bytes);
 	return {
 		tool: "git_diff",
 		path: path ?? void 0,
@@ -1343,6 +1358,9 @@ const grepTool = defineTool({
 		pattern: z.string(),
 		path: z.string().optional()
 	}),
+	parallelSafe: true,
+	mutatesWorkspace: false,
+	resourceKeys: (args) => [`grep:${args.path ?? "."}`],
 	execute: (context, args) => grepWorkspace(context.workspaceRoot, args, {
 		pathEnv: context.pathEnv,
 		logger: context.logger
@@ -1644,6 +1662,8 @@ const READ_ONLY_COMMANDS = new Set([
 	"find",
 	"fd",
 	"cat",
+	"sed",
+	"sort",
 	"head",
 	"tail",
 	"wc",
@@ -1851,6 +1871,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);
 	}
 }
@@ -1873,6 +1894,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] ?? "";
@@ -2232,6 +2335,9 @@ const listFilesTool = defineTool({
 		recursive: z.boolean().optional().default(false),
 		limit: z.number().int().min(1).max(2e3).optional().default(500)
 	}),
+	parallelSafe: true,
+	mutatesWorkspace: false,
+	resourceKeys: (args) => [`dir:${args.path}`],
 	execute: (context, args) => listWorkspaceFiles(context.workspaceRoot, args)
 });
 async function listWorkspaceFiles(workspaceRoot, args) {
@@ -2310,11 +2416,264 @@ function resolveWorkspaceScopedPath$1(workspaceRoot, path) {
 		relativePath: relativePath || "."
 	};
 }
+//#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. Do not use plan_todo just to report completed work before a final answer. 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() }),
+	parallelSafe: true,
+	mutatesWorkspace: false,
+	resourceKeys: (args) => [`file:${args.path}`],
 	execute: (context, args) => readWorkspaceFile(context.workspaceRoot, args.path)
 });
 async function readWorkspaceFile(workspaceRoot, path) {
@@ -2331,16 +2690,52 @@ async function readWorkspaceFile(workspaceRoot, path) {
 		hash: `sha256:${createHash("sha256").update(bytes).digest("hex")}`
 	};
 }
+const taskTool = defineTool({
+	name: "task",
+	description: "Delegate a focused prompt to a constrained child agent session.",
+	prompt: "task: delegate focused read-only research or isolated analysis to a child agent session. Use it when parallel context gathering would help. To use it, reply with only JSON: {\"tool\":\"task\",\"args\":{\"description\":\"Inspect runtime event flow\",\"prompt\":\"Read the runtime and summarize how events are emitted.\",\"subagent_type\":\"explore\"}}",
+	argsSchema: z.object({
+		description: z.string().min(1),
+		prompt: z.string().min(1),
+		subagent_type: z.string().optional(),
+		task_id: z.string().optional()
+	}),
+	async execute(context, args) {
+		if (!context.subagents) throw new Error("task requires a runtime subagent manager.");
+		const result = await context.subagents.runTask({
+			description: args.description,
+			prompt: args.prompt,
+			subagentType: args.subagent_type,
+			taskId: args.task_id,
+			parentToolCallId: context.toolCallId ?? args.task_id ?? "task",
+			eventSink: context.eventSink,
+			abortSignal: context.abortSignal
+		});
+		return {
+			tool: "task",
+			childSessionId: result.sessionId,
+			status: result.status,
+			profileId: result.profileId,
+			content: [
+				`Task ${result.status}: ${args.description}`,
+				`child_session: ${result.sessionId}`,
+				`profile: ${result.profileId}`,
+				"",
+				result.result
+			].join("\n")
+		};
+	}
+});
 const writeFileTool = defineTool({
 	name: "write_file",
-	description: "Create a new UTF-8 file inside the workspace, or explicitly replace one with an expected 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, and replace an existing whole file only with overwrite:true and expected_hash from read_file. To use it, 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}}",
+	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(),
-		content: z.string(),
-		create_parent_dirs: z.boolean().optional(),
-		overwrite: z.boolean().optional(),
-		expected_hash: z.string().optional()
+		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 })
 });
@@ -2396,12 +2791,12 @@ async function writeWorkspaceFile(workspaceRoot, args, options = {}) {
 	});
 }
 async function overwriteExistingFile(workspaceRoot, scopedPath, args, existingTarget, options) {
-	if (!args.expected_hash) throw new Error(`write_file overwrite requires expected_hash for ${scopedPath.relativePath}.`);
+	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_hash !== beforeHash) throw new Error(`write_file expected_hash did not match ${scopedPath.relativePath}.`);
+	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);
@@ -2543,6 +2938,8 @@ function isNodeError$2(error) {
 //#endregion
 //#region src/agent/tools/registry.ts
 const toolRegistry = {
+	[taskTool.name]: taskTool,
+	[planTodoTool.name]: planTodoTool,
 	[readFileTool.name]: readFileTool,
 	[listFilesTool.name]: listFilesTool,
 	[grepTool.name]: grepTool,
@@ -2562,8 +2959,16 @@ function isToolName(name) {
 function getToolDefinition(name) {
 	return toolRegistry[name];
 }
-function getToolPromptLines() {
-	return Object.values(toolRegistry).map((tool) => tool.prompt);
+function getToolPromptLines(filter) {
+	return getToolDefinitionsForPermissions(filter).map((tool) => tool.prompt);
+}
+function getToolDefinitionsForPermissions(filter) {
+	return Object.entries(toolRegistry).filter(([name]) => filter?.(name) ?? true).map(([, tool]) => tool);
+}
+function isParallelSafeToolName(name) {
+	if (!isToolName(name)) return false;
+	const definition = toolRegistry[name];
+	return Boolean(definition.parallelSafe && !definition.mutatesWorkspace && !definition.requiresExclusiveWorkspace);
 }
 //#endregion
 //#region src/agent/tools/xml-parser.ts
@@ -2652,7 +3057,7 @@ function parseToolCallWithSource(text, allowedSources = ["text-json", "text-xml"
 	if (allowedSources.includes("text-json")) {
 		const json = parseJsonToolCall(text);
 		if (json) return {
-			call: json,
+			...json,
 			source: "text-json"
 		};
 	}
@@ -2660,7 +3065,8 @@ function parseToolCallWithSource(text, allowedSources = ["text-json", "text-xml"
 		const xml = parseXmlToolCall(text);
 		if (xml) return {
 			call: xml,
-			source: "text-xml"
+			source: "text-xml",
+			remainder: ""
 		};
 	}
 }
@@ -2675,12 +3081,16 @@ function parseNativeToolCall(toolName, args) {
 	};
 }
 function parseJsonToolCall(text) {
-	const trimmed = extractToolJsonCandidate(stripJsonFence(text.trim()));
+	const { json, remainder } = extractToolJsonCandidate(stripJsonFence(text.trim()));
 	let value;
 	try {
-		value = JSON.parse(trimmed);
+		value = JSON.parse(json);
 	} catch {
-		return;
+		try {
+			value = JSON.parse(escapeControlCharactersInJsonStrings(json));
+		} catch {
+			return;
+		}
 	}
 	if (!isRecord$1(value) || typeof value.tool !== "string") return;
 	if (!isToolName(value.tool)) return;
@@ -2688,17 +3098,29 @@ function parseJsonToolCall(text) {
 	const parsed = definition.argsSchema.safeParse(value.args);
 	if (!parsed.success) return;
 	return {
-		tool: definition.name,
-		args: parsed.data
+		call: {
+			tool: definition.name,
+			args: parsed.data
+		},
+		remainder: remainder.trim()
 	};
 }
 function stripJsonFence(text) {
 	return text.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i)?.[1] ?? text;
 }
 function extractToolJsonCandidate(text) {
-	if (!text.startsWith("{")) return text;
+	if (!text.startsWith("{")) return {
+		json: text,
+		remainder: ""
+	};
 	const endIndex = findJsonObjectEnd(text);
-	return endIndex === void 0 ? text : text.slice(0, endIndex + 1);
+	return endIndex === void 0 ? {
+		json: text,
+		remainder: ""
+	} : {
+		json: text.slice(0, endIndex + 1),
+		remainder: text.slice(endIndex + 1)
+	};
 }
 function findJsonObjectEnd(text) {
 	let depth = 0;
@@ -2720,6 +3142,39 @@ function findJsonObjectEnd(text) {
 		}
 	}
 }
+function escapeControlCharactersInJsonStrings(text) {
+	let result = "";
+	let inString = false;
+	let escaped = false;
+	for (let index = 0; index < text.length; index += 1) {
+		const char = text[index];
+		if (!inString) {
+			result += char;
+			if (char === "\"") inString = true;
+			continue;
+		}
+		if (escaped) {
+			result += char;
+			escaped = false;
+			continue;
+		}
+		if (char === "\\") {
+			result += char;
+			escaped = true;
+			continue;
+		}
+		if (char === "\"") {
+			result += char;
+			inString = false;
+			continue;
+		}
+		if (char === "\n") result += "\\n";
+		else if (char === "\r") result += "\\r";
+		else if (char === "	") result += "\\t";
+		else result += char;
+	}
+	return result;
+}
 function isRecord$1(value) {
 	return typeof value === "object" && value !== null;
 }
@@ -2769,25 +3224,41 @@ 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,
+			providerOptions: buildProviderOptions(resolved.providerId, resolved.providerConfig),
+			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) {
 		const resolved = this.resolveModel(request.purpose ?? "agent.primary");
 		const override = request.toolProtocol ?? resolved.modelConfig.toolProtocol ?? resolved.providerConfig.toolProtocol ?? "auto";
 		const attempts = [];
+		if (override === "auto" && shouldUseTextProtocolForOpenRouterStreaming(request, resolved)) {
+			attempts.push({
+				protocol: "native-openai-compatible",
+				status: "skipped",
+				reason: "openrouter streaming auto uses text-json"
+			});
+			return this.generateTextAgentStep(request, resolved, attempts, "openrouter streaming auto uses text JSON protocol", false, ["text-json"]);
+		}
 		if (override === "native" || override === "auto") try {
 			const result = await this.generateNativeAgentStep(request, resolved, attempts);
-			if (result.toolCalls.length > 0 || override === "native") return result;
+			if (result.toolCalls.length > 0) return result;
 			const parsedTextCall = parseToolCallWithSource(result.text);
 			if (parsedTextCall) {
 				const fallbackProtocol = parsedTextCall.source === "text-xml" ? "text-xml" : "text-json";
@@ -2811,7 +3282,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",
@@ -2828,17 +3299,19 @@ var ModelGateway = class ModelGateway {
 		return this.generateTextAgentStep(request, resolved, attempts, override === "text-xml" ? "forced text XML protocol" : "forced text JSON protocol", false, override === "text-xml" ? ["text-xml"] : ["text-json"]);
 	}
 	async *streamText(request) {
+		const resolved = this.resolveModel(request.purpose);
 		yield* streamText({
-			model: this.resolveModel(request.purpose).model,
+			model: resolved.model,
 			system: request.system,
 			prompt: request.prompt,
+			providerOptions: buildProviderOptions(resolved.providerId, resolved.providerConfig),
 			abortSignal: request.abortSignal
 		}).textStream;
 	}
 	async generateNativeAgentStep(request, resolved, attempts) {
 		const providerOptions = buildNativeProviderOptions(resolved.providerId, resolved.providerConfig);
 		const openRouterRoutingApplied = hasOpenRouterRoutingOptions(providerOptions, resolved.providerId);
-		const result = await generateText({
+		const result = request.onReasoning ? await this.streamNativeAgentStep(request, resolved, providerOptions) : await generateText({
 			model: resolved.model,
 			system: request.system,
 			prompt: request.prompt,
@@ -2847,6 +3320,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.`);
@@ -2866,6 +3344,7 @@ var ModelGateway = class ModelGateway {
 			providerId: resolved.providerId,
 			modelId: resolved.modelId,
 			purpose: resolved.purpose,
+			...usage ? { usage } : {},
 			toolCalls,
 			toolProtocol: "native-openai-compatible",
 			protocolAttempts: attempts,
@@ -2875,12 +3354,18 @@ var ModelGateway = class ModelGateway {
 		};
 	}
 	async generateTextAgentStep(request, resolved, attempts, fallbackReason, providerRejectedTools, allowedSources) {
-		const result = await generateText({
+		const result = request.onReasoning ? await this.streamTextAgentStep(request, resolved) : await generateText({
 			model: resolved.model,
 			system: request.system,
 			prompt: request.prompt,
+			providerOptions: buildProviderOptions(resolved.providerId, resolved.providerConfig),
 			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;
@@ -2894,6 +3379,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,
@@ -2908,35 +3394,209 @@ var ModelGateway = class ModelGateway {
 			openRouterRoutingApplied: false
 		};
 	}
-};
-function resolveApiKey(config) {
-	if (config.apiKey !== void 0) return config.apiKey;
-	if (config.apiKeyEnv === void 0) return;
-	return process.env[config.apiKeyEnv];
-}
-function buildNativeProviderOptions(providerId, config) {
-	const options = { parallel_tool_calls: false };
-	if (shouldApplyOpenRouterRoutingOptions(providerId, config)) options.provider = { require_parameters: true };
-	return { [providerId]: options };
-}
-function shouldApplyOpenRouterRoutingOptions(providerId, config) {
-	if (config.openRouterToolRouting === "force") return true;
-	if (config.openRouterToolRouting === "off") return false;
-	return providerId.toLowerCase().includes("openrouter") || config.baseURL.toLowerCase().includes("openrouter.ai");
-}
-function hasOpenRouterRoutingOptions(providerOptions, providerId) {
-	const options = providerOptions[providerId];
-	return Boolean(options && typeof options === "object" && "provider" in options);
+	async streamNativeAgentStep(request, resolved, providerOptions) {
+		const result = streamText({
+			model: resolved.model,
+			system: request.system,
+			prompt: request.prompt,
+			tools: toAiSdkToolSet(request.tools),
+			toolChoice: "auto",
+			providerOptions,
+			abortSignal: request.abortSignal,
+			includeRawChunks: true
+		});
+		guardStreamTextResultRejections(result);
+		let rawUsageBody;
+		let sawReasoningDelta = false;
+		let reasoningText;
+		let text;
+		let toolCalls;
+		let usage;
+		let warnings;
+		let response;
+		try {
+			({rawUsageBody, sawReasoningDelta} = await consumeReasoningStream(result.fullStream, request.onReasoning));
+			[text, toolCalls, usage, warnings, response, reasoningText] = await Promise.all([
+				result.text,
+				result.toolCalls,
+				result.usage,
+				result.warnings,
+				result.response,
+				result.reasoningText
+			]);
+		} catch (error) {
+			await settleRejectedStreamTextResult(result);
+			throw error;
+		}
+		await emitReasoningSummary(request.onReasoning, sawReasoningDelta, reasoningText);
+		return {
+			text,
+			toolCalls,
+			usage,
+			warnings,
+			response: withRawUsageBody(response, rawUsageBody)
+		};
+	}
+	async streamTextAgentStep(request, resolved) {
+		const result = streamText({
+			model: resolved.model,
+			system: request.system,
+			prompt: request.prompt,
+			providerOptions: buildProviderOptions(resolved.providerId, resolved.providerConfig),
+			abortSignal: request.abortSignal,
+			includeRawChunks: true
+		});
+		guardStreamTextResultRejections(result);
+		let rawUsageBody;
+		let sawReasoningDelta = false;
+		let reasoningText;
+		let text;
+		let usage;
+		let warnings;
+		let response;
+		try {
+			({rawUsageBody, sawReasoningDelta} = await consumeReasoningStream(result.fullStream, request.onReasoning));
+			[text, usage, warnings, response, reasoningText] = await Promise.all([
+				result.text,
+				result.usage,
+				result.warnings,
+				result.response,
+				result.reasoningText
+			]);
+		} catch (error) {
+			await settleRejectedStreamTextResult(result);
+			throw error;
+		}
+		await emitReasoningSummary(request.onReasoning, sawReasoningDelta, reasoningText);
+		return {
+			text,
+			usage,
+			warnings,
+			response: withRawUsageBody(response, rawUsageBody)
+		};
+	}
+};
+function guardStreamTextResultRejections(result) {
+	for (const promise of [
+		result.text,
+		result.toolCalls,
+		result.usage,
+		result.warnings,
+		result.response,
+		result.reasoningText
+	]) if (promise) Promise.resolve(promise).catch(() => {});
+}
+async function settleRejectedStreamTextResult(result) {
+	await Promise.allSettled([
+		result.text,
+		result.toolCalls,
+		result.usage,
+		result.warnings,
+		result.response,
+		result.reasoningText
+	].filter((promise) => promise !== void 0).map((promise) => Promise.resolve(promise)));
+}
+async function consumeReasoningStream(stream, onReasoning) {
+	let sawReasoningDelta = false;
+	let rawUsageBody;
+	for await (const part of stream) {
+		if (!part || typeof part !== "object") continue;
+		const typedPart = part;
+		if (typedPart.type === "error") throw typedPart.error;
+		if (typedPart.type === "raw" && hasUsageCostBody(typedPart.rawValue)) {
+			rawUsageBody = typedPart.rawValue;
+			continue;
+		}
+		if (typedPart.type !== "reasoning-delta") continue;
+		const text = typeof typedPart.text === "string" ? typedPart.text : typedPart.delta;
+		if (typeof text !== "string" || text.trim().length === 0) continue;
+		sawReasoningDelta = true;
+		await onReasoning?.({
+			type: "delta",
+			text
+		});
+	}
+	return rawUsageBody === void 0 ? { sawReasoningDelta } : {
+		sawReasoningDelta,
+		rawUsageBody
+	};
+}
+async function emitReasoningSummary(onReasoning, sawReasoningDelta, reasoningText) {
+	if (sawReasoningDelta || !reasoningText || reasoningText.trim().length === 0) return;
+	await onReasoning?.({
+		type: "summary",
+		text: reasoningText
+	});
+}
+function hasUsageCostBody(value) {
+	return Boolean(value && typeof value === "object" && "usage" in value && value.usage && typeof value.usage === "object");
+}
+function withRawUsageBody(response, rawUsageBody) {
+	return rawUsageBody === void 0 ? response : {
+		...response,
+		body: rawUsageBody
+	};
+}
+function resolveApiKey(config) {
+	if (config.apiKey !== void 0) return config.apiKey;
+	if (config.apiKeyEnv === void 0) return;
+	return process.env[config.apiKeyEnv];
+}
+function buildProviderOptions(providerId, config) {
+	const options = {};
+	if (config.service_tier !== void 0) options.service_tier = config.service_tier;
+	return { [providerId]: options };
+}
+function buildNativeProviderOptions(providerId, config) {
+	const options = {
+		...buildProviderOptions(providerId, config)[providerId],
+		parallel_tool_calls: false
+	};
+	if (shouldApplyOpenRouterRoutingOptions(providerId, config)) options.provider = { require_parameters: true };
+	return { [providerId]: options };
+}
+function shouldApplyOpenRouterRoutingOptions(providerId, config) {
+	if (config.openRouterToolRouting === "force") return true;
+	if (config.openRouterToolRouting === "off") return false;
+	return isOpenRouterProvider$1(providerId, config);
+}
+function isOpenRouterProvider$1(providerId, config) {
+	return providerId.toLowerCase().includes("openrouter") || config.baseURL.toLowerCase().includes("openrouter.ai");
+}
+function shouldUseTextProtocolForOpenRouterStreaming(request, resolved) {
+	return request.onReasoning !== void 0 && isOpenRouterProvider$1(resolved.providerId, resolved.providerConfig);
+}
+function hasOpenRouterRoutingOptions(providerOptions, providerId) {
+	const options = 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$1(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
@@ -2946,8 +3606,6 @@ const modelPurposeSchema = z.enum([
 	"agent.fast",
 	"kb.scan",
 	"kb.summarize",
-	"kb.extract",
-	"kb.embed",
 	"fallback"
 ]);
 const modelPurposes = modelPurposeSchema.options;
@@ -2957,6 +3615,10 @@ const toolProtocolSchema = z.enum([
 	"text-json",
 	"text-xml"
 ]);
+const openRouterAttributionHeaders = {
+	"HTTP-Referer": "https://topchester.com",
+	"X-Title": "Topchester"
+};
 const providerSchema = z.object({
 	type: z.literal("openai-compatible"),
 	baseURL: z.string().url(),
@@ -2964,6 +3626,7 @@ const providerSchema = z.object({
 	apiKey: z.string().optional(),
 	headers: z.record(z.string(), z.string()).optional(),
 	supportsStructuredOutputs: z.boolean().optional(),
+	service_tier: z.enum(["flex", "priority"]).optional(),
 	toolProtocol: toolProtocolSchema.optional(),
 	openRouterToolRouting: z.enum([
 		"auto",
@@ -3042,7 +3705,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) {
@@ -3078,6 +3741,7 @@ function normalizeConfigInput(value) {
 		ensureKnownProvider(providers, kbSummarizeModelRef.provider);
 		delete models["kb.summarize"];
 	}
+	applyKnownProviderDefaults(providers);
 	return {
 		...value,
 		models: {
@@ -3128,12 +3792,30 @@ function ensureKnownProvider(providers, provider) {
 		baseURL: "https://openrouter.ai/api/v1",
 		apiKeyEnv: "OPENROUTER_API_KEY",
 		supportsStructuredOutputs: true,
-		headers: {
-			"HTTP-Referer": "https://topchester.com",
-			"X-Title": "Topchester"
-		}
+		headers: { ...openRouterAttributionHeaders }
 	};
 }
+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";
+		}
+		if (isOpenRouterProvider(providerId, provider.baseURL)) provider.headers = {
+			...openRouterAttributionHeaders,
+			...isPlainObject(provider.headers) ? provider.headers : {}
+		};
+	}
+}
+function isOpenRouterProvider(providerId, baseURL) {
+	return providerId.toLowerCase().includes("openrouter") || baseURL.toLowerCase().includes("openrouter.ai");
+}
+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;
@@ -3147,7 +3829,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
@@ -3241,107 +3923,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";
@@ -3674,6 +4255,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" });
@@ -3685,7 +4274,7 @@ const l1FileSymbolSchema = z.object({
 	kind: nonEmptyStringSchema,
 	name: nonEmptyStringSchema,
 	exported: z.boolean(),
-	summary: nonEmptyStringSchema
+	summary: nonEmptyStringSchema.optional()
 }).strict();
 const l1FileEvidenceSchema = z.object({
 	kind: nonEmptyStringSchema,
@@ -3702,6 +4291,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),
@@ -3710,6 +4300,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}`, {
@@ -3777,6 +4370,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",
@@ -3819,6 +4529,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 {
@@ -3878,7 +4590,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");
@@ -3887,6 +4603,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,
@@ -3899,6 +4644,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: [],
@@ -3907,6 +4653,9 @@ function buildL1FileEntryPrompt(input) {
 			module_ids: [],
 			feature_ids: [],
 			test_ids: [],
+			declared_test_targets: [],
+			likely_test_targets: [],
+			tested_by: [],
 			evidence: [{
 				kind: "path",
 				value: "<path>"
@@ -3944,41 +4693,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 [];
@@ -3986,8 +4743,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 [];
@@ -3995,14 +4751,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 = [];
@@ -4404,11 +5182,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) {
@@ -4522,25 +5300,449 @@ function isNodeError(error) {
 	return error instanceof Error && "code" in error;
 }
 //#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;
+//#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);
 		}
-		rendered.push(inCodeBlock ? applyCodeBlockBackground(line) : line);
 	}
-	return rendered;
-}
-function unwrapMarkdownCodeFences(text) {
-	return text.replace(/^```(?:markdown|md)\s*\n([\s\S]*?)\n```$/gim, "$1");
+	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);
 }
-function getMarkdownTheme() {
+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,
@@ -4607,6 +5809,12 @@ function agentMessage(text, meta) {
 		meta
 	};
 }
+function thinkingMessage(text) {
+	return {
+		kind: "thinking",
+		text
+	};
+}
 function toolCallMessage(call, label, resultSummary) {
 	return resultSummary === void 0 ? {
 		kind: "tool_call",
@@ -4619,6 +5827,12 @@ function toolCallMessage(call, label, resultSummary) {
 		resultSummary
 	};
 }
+function subagentMessage(message) {
+	return {
+		kind: "subagent",
+		...message
+	};
+}
 function modalMessage(message) {
 	return {
 		kind: "modal",
@@ -4628,6 +5842,8 @@ function modalMessage(message) {
 function renderChatMessage(message, options = {}) {
 	if (message.kind === "modal") return renderChatModal(message, options.selectedActionIndex);
 	if (message.kind === "tool_call") return renderToolCallMessage(message);
+	if (message.kind === "subagent") return renderSubagentMessage(message);
+	if (message.kind === "thinking") return message.text.split("\n").map((line) => ui.muted(line));
 	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);
@@ -4660,6 +5876,18 @@ function renderToolCallMessage(message) {
 	const visibleLabel = message.resultSummary && !message.label.includes(message.resultSummary) ? `${message.label} ${message.resultSummary}` : message.label;
 	return [`   ${ui.muted(expandTabs(visibleLabel))}`];
 }
+function renderSubagentMessage(message) {
+	const label = message.title ?? shortSessionId(message.sessionId);
+	switch (message.status) {
+		case "running": return [`   ${ui.muted(`↳ task: ${label} (running)`)}`];
+		case "event": return message.text ? [`   ${ui.muted(`↳ task: ${label}: ${message.text}`)}`] : [];
+		case "completed": return [`   ${ui.muted(`↳ task: ${label} (completed)`)}`, ...message.text ? [`     ${message.text}`] : []];
+		case "failed": return [`   ${ui.warn(`↳ task: ${label} (failed)`)}`, ...message.text ? [`     ${message.text}`] : []];
+	}
+}
+function shortSessionId(sessionId) {
+	return sessionId.length <= 8 ? sessionId : sessionId.slice(0, 8);
+}
 function expandTabs(line) {
 	let column = 0;
 	let expanded = "";
@@ -4728,11 +5956,21 @@ const jsonValueSchema = z.lazy(() => z.union([
 const sessionMetadataSchema = z.object({
 	version: z.literal(1),
 	sessionId: z.string(),
+	rootSessionId: z.string().optional(),
+	parentSessionId: z.string().optional(),
+	parentToolCallId: z.string().optional(),
+	source: z.enum(["user", "subagent"]).optional(),
+	agentProfileId: z.string().optional(),
+	title: z.string().optional(),
 	workspaceRoot: z.string().min(1),
 	createdAt: isoTimestampSchema,
 	updatedAt: isoTimestampSchema,
 	lastEventId: z.number().int().min(0)
-});
+}).transform((metadata) => ({
+	...metadata,
+	rootSessionId: metadata.rootSessionId ?? metadata.sessionId,
+	source: metadata.source ?? "user"
+}));
 const eventEnvelopeSchema = z.object({
 	version: z.literal(1),
 	id: z.number().int().positive(),
@@ -4753,6 +5991,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()
@@ -4771,14 +6022,74 @@ const choicePayloadSchema = z.object({
 		value: z.string().optional()
 	}))
 });
+const subagentLifecycleBasePayloadSchema = z.object({
+	sessionId: z.string(),
+	parentSessionId: z.string(),
+	parentToolCallId: z.string()
+});
+const subagentStartedPayloadSchema = subagentLifecycleBasePayloadSchema.extend({
+	kind: z.literal("subagent_started"),
+	agentProfileId: z.string().optional(),
+	title: z.string().optional()
+});
+const subagentEventPayloadSchema = subagentLifecycleBasePayloadSchema.extend({
+	kind: z.literal("subagent_event"),
+	event: z.record(z.string(), jsonValueSchema)
+});
+const subagentCompletedPayloadSchema = subagentLifecycleBasePayloadSchema.extend({
+	kind: z.literal("subagent_completed"),
+	result: z.string().optional()
+});
+const subagentFailedPayloadSchema = subagentLifecycleBasePayloadSchema.extend({
+	kind: z.literal("subagent_failed"),
+	error: z.string()
+});
 const sessionEventPayloadSchema = z.discriminatedUnion("kind", [
 	messagePayloadSchema,
 	toolCallPayloadSchema,
+	taskPlanPayloadSchema,
 	statusPayloadSchema,
 	knowledgeStatusPayloadSchema,
-	choicePayloadSchema
+	choicePayloadSchema,
+	subagentStartedPayloadSchema,
+	subagentEventPayloadSchema,
+	subagentCompletedPayloadSchema,
+	subagentFailedPayloadSchema
 ]);
 const sessionEventSchema = z.intersection(eventEnvelopeSchema, sessionEventPayloadSchema);
+const sessionEventPayload = {
+	subagentStarted(reference, options = {}) {
+		return {
+			kind: "subagent_started",
+			...reference,
+			...options
+		};
+	},
+	subagentEvent(reference, event) {
+		return {
+			kind: "subagent_event",
+			...reference,
+			event
+		};
+	},
+	subagentCompleted(reference, result) {
+		return result === void 0 ? {
+			kind: "subagent_completed",
+			...reference
+		} : {
+			kind: "subagent_completed",
+			...reference,
+			result
+		};
+	},
+	subagentFailed(reference, error) {
+		return {
+			kind: "subagent_failed",
+			...reference,
+			error
+		};
+	}
+};
 //#endregion
 //#region src/session/store.ts
 const SESSION_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
@@ -4794,6 +6105,8 @@ async function createSession(workspaceRoot) {
 	const metadata = {
 		version: 1,
 		sessionId,
+		rootSessionId: sessionId,
+		source: "user",
 		workspaceRoot,
 		createdAt,
 		updatedAt: createdAt,
@@ -4804,6 +6117,41 @@ async function createSession(workspaceRoot) {
 	await writeFile(eventsPath, "", { flag: "wx" });
 	return buildHandle(sessionDir, metadata);
 }
+async function createChildSession(workspaceRoot, options) {
+	validateSessionId(options.parent.sessionId);
+	const sessionId = generateSessionId();
+	const sessionDir = join(getTopchesterSessionsPath(workspaceRoot), sessionId);
+	const metadataPath = join(sessionDir, "metadata.json");
+	const eventsPath = join(sessionDir, "events.jsonl");
+	const createdAt = (/* @__PURE__ */ new Date()).toISOString();
+	const metadata = {
+		version: 1,
+		sessionId,
+		rootSessionId: options.parent.metadata.rootSessionId,
+		parentSessionId: options.parent.sessionId,
+		parentToolCallId: options.parentToolCallId,
+		source: "subagent",
+		...options.agentProfileId === void 0 ? {} : { agentProfileId: options.agentProfileId },
+		...options.title === void 0 ? {} : { title: options.title },
+		workspaceRoot,
+		createdAt,
+		updatedAt: createdAt,
+		lastEventId: 0
+	};
+	await mkdir(sessionDir, { recursive: true });
+	await writeMetadata(metadataPath, metadata);
+	await writeFile(eventsPath, "", { flag: "wx" });
+	const child = buildHandle(sessionDir, metadata);
+	if (options.recordParentEvent ?? true) await options.parent.append(sessionEventPayload.subagentStarted({
+		sessionId: child.sessionId,
+		parentSessionId: options.parent.sessionId,
+		parentToolCallId: options.parentToolCallId
+	}, {
+		...options.agentProfileId === void 0 ? {} : { agentProfileId: options.agentProfileId },
+		...options.title === void 0 ? {} : { title: options.title }
+	}));
+	return child;
+}
 async function loadSessionForAppend(workspaceRoot, sessionId) {
 	const loaded = await loadSession(workspaceRoot, sessionId);
 	return buildHandle(loaded.sessionDir, loaded.metadata);
@@ -4854,6 +6202,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":
@@ -4869,7 +6218,17 @@ function rehydrateSession(events) {
 		case "tool_call":
 			messages.push(toolCallMessage(event.call, event.label));
 			break;
+		case "task_plan":
+			taskPlan = {
+				items: event.items,
+				updatedAt: event.updatedAt
+			};
+			break;
 		case "knowledge_status": break;
+		case "subagent_started":
+		case "subagent_event":
+		case "subagent_completed":
+		case "subagent_failed": break;
 		case "choice":
 			messages.push({
 				kind: "modal",
@@ -4886,7 +6245,8 @@ function rehydrateSession(events) {
 	}
 	return {
 		messages,
-		status
+		status,
+		...taskPlan === void 0 ? {} : { taskPlan }
 	};
 }
 function buildHandle(sessionDir, metadata) {
@@ -5167,19 +6527,25 @@ var BusyIndicator = class {
 			this.tui.requestRender();
 		}, 80);
 	}
-	stop() {
+	stop(options = {}) {
 		if (this.timer) {
 			clearInterval(this.timer);
 			this.timer = void 0;
 		}
 		this.app.setPromptHint(void 0);
-		this.app.setEphemeralLine(void 0);
+		if (options.clearEphemeralLine ?? true) this.app.setEphemeralLine(void 0);
 	}
 	setActivity(activity) {
 		this.activityOverride = activity;
 		this.render();
 		this.tui.requestRender();
 	}
+	clearActivity() {
+		if (!this.activityOverride) return;
+		this.activityOverride = void 0;
+		this.render();
+		this.tui.requestRender();
+	}
 	render() {
 		if (this.activityOverride) {
 			this.app.setEphemeralLine(`${this.frames[this.index]} ${this.activityOverride}`);
@@ -5190,6 +6556,33 @@ var BusyIndicator = class {
 		this.app.setEphemeralLine(`${this.frames[this.index]} ${this.options.activities[activityIndex]}`);
 	}
 };
+var ReasoningTailBuffer = class {
+	text = "";
+	get hasText() {
+		return this.text.length > 0;
+	}
+	get value() {
+		return this.text;
+	}
+	append(delta) {
+		const normalized = normalizeReasoningText(`${this.text}${delta}`);
+		if (!normalized) return;
+		this.text = normalized;
+		return this.text;
+	}
+	replace(summary) {
+		const normalized = normalizeReasoningText(summary);
+		if (!normalized) return;
+		this.text = normalized;
+		return this.text;
+	}
+	clear() {
+		this.text = "";
+	}
+};
+function normalizeReasoningText(text) {
+	return text.replace(/\s+/gu, " ").trim();
+}
 //#endregion
 //#region src/agent/commands.ts
 const slashCommandSuggestions = [
@@ -5264,6 +6657,96 @@ async function executeKbCommand(args, context) {
 	return { messages: ["Usage: /kb init, /kb compile, /kb sync, /kb reset, or /kb status"] };
 }
 //#endregion
+//#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
+		};
+	},
+	subagentStarted(options) {
+		return {
+			type: "subagent_started",
+			...options
+		};
+	},
+	subagentEvent(options, event) {
+		return {
+			type: "subagent_event",
+			...options,
+			event
+		};
+	},
+	subagentCompleted(options) {
+		return {
+			type: "subagent_completed",
+			...options
+		};
+	},
+	subagentFailed(options) {
+		return {
+			type: "subagent_failed",
+			...options
+		};
+	}
+};
+function choiceAction(label, value) {
+	return value === void 0 ? { label } : {
+		label,
+		value
+	};
+}
+//#endregion
 //#region src/tui/keys.ts
 function isUpKey(data) {
 	return matchesKey(data, "up") || data === "\x1B[A";
@@ -5274,6 +6757,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 === "	";
 }
@@ -5380,12 +6866,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,
 		"┌──────────────────────────────────────────────────────────────────────┐",
 		"│ >                                                                    │",
 		"└──────────────────────────────────────────────────────────────────────┘",
@@ -5467,23 +6955,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;
@@ -5494,14 +6994,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);
@@ -5514,6 +7006,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";
 	}
@@ -5536,7 +7046,10 @@ 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) => {
@@ -5550,16 +7063,18 @@ var ChatLayout = class {
 					text: message.text
 				}];
 				case "system":
+				case "thinking":
 				case "tool_call":
+				case "subagent":
 				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")) {
@@ -5568,15 +7083,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);
@@ -5604,6 +7119,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;
 	}
@@ -5619,17 +7135,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 [];
@@ -5676,6 +7244,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;
 		}
@@ -5718,17 +7294,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) {
@@ -5747,19 +7502,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()];
@@ -5772,6 +7527,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);
@@ -5780,8 +7536,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
@@ -5793,58 +7556,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();
@@ -5875,22 +7586,102 @@ function isAbortError(error) {
 	return error.name === "AbortError" || error.message.toLowerCase().includes("aborted");
 }
 //#endregion
+//#region src/agent/profiles.ts
+const READ_ONLY_TOOLS = [
+	"read_file",
+	"list_files",
+	"grep",
+	"find_file",
+	"git_status",
+	"git_diff",
+	"git_log"
+];
+const PRIMARY_AGENT_PROFILE = {
+	id: "primary",
+	displayName: "Primary",
+	mode: "primary",
+	promptAdditions: [],
+	modelPurpose: "agent.primary",
+	toolPermissionDefault: "allow",
+	allowedTools: [],
+	deniedTools: []
+};
+const AGENT_PROFILES = [PRIMARY_AGENT_PROFILE, ...[{
+	id: "explore",
+	displayName: "Explore",
+	mode: "subagent",
+	promptAdditions: ["You are running as a read-only exploration subagent. Inspect the workspace and return concise findings to the parent agent."],
+	modelPurpose: "agent.fast",
+	toolPermissionDefault: "deny",
+	allowedTools: READ_ONLY_TOOLS,
+	deniedTools: ["task", "plan_todo"]
+}, {
+	id: "general",
+	displayName: "General",
+	mode: "subagent",
+	promptAdditions: ["You are running as a constrained subagent. Work only on the delegated prompt and return a concise result."],
+	modelPurpose: "agent.primary",
+	toolPermissionDefault: "allow",
+	allowedTools: [],
+	deniedTools: ["task", "plan_todo"]
+}]];
+function resolveAgentProfile(profileId = PRIMARY_AGENT_PROFILE.id) {
+	const profile = AGENT_PROFILES.find((candidate) => candidate.id === profileId);
+	if (!profile) throw new Error(`Unknown agent profile "${profileId}".`);
+	return profile;
+}
+function createToolPermissionView(profile, parent = {}) {
+	const deniedTools = new Set(profile.deniedTools);
+	for (const tool of parent.deniedTools ?? []) deniedTools.add(tool);
+	return {
+		profileId: profile.id,
+		defaultPermission: profile.toolPermissionDefault,
+		allowedTools: new Set(profile.allowedTools),
+		deniedTools
+	};
+}
+function isToolAllowed(permissionView, toolName) {
+	if (!isRegisteredToolName(toolName)) return false;
+	if (permissionView.deniedTools.has(toolName)) return false;
+	if (permissionView.defaultPermission === "deny") return permissionView.allowedTools.has(toolName);
+	return true;
+}
+function getProfileToolDefinitions(permissionView) {
+	return getToolDefinitionsForPermissions((toolName) => isToolAllowed(permissionView, toolName));
+}
+function isRegisteredToolName(toolName) {
+	return toolName in toolRegistry;
+}
+//#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,
+		profile: options.profile,
+		permissions: options.permissions,
+		subagents: options.subagents,
+		eventSink: options.eventSink,
+		abortSignal: options.abortSignal,
+		toolCallId: options.toolCallId
 	};
-	options.logger?.debug({
-		event: "tool_call",
-		tool: call.tool,
-		args: summarizeToolArgs(call)
-	}, "tool call");
 	try {
-		const result = await definition.execute(context, call.args);
+		if (!isToolName(call.tool)) throw new Error(`Unknown tool "${call.tool}".`);
+		if (options.permissions && !isToolAllowed(options.permissions, call.tool)) throw new Error(`Tool "${call.tool}" is not allowed for agent profile "${options.permissions.profileId}".`);
+		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",
@@ -5910,23 +7701,40 @@ 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),
-		expectedHashProvided: Boolean(call.args.expected_hash)
+		expectedCurrentHashProvided: Boolean(call.args.expected_current_hash)
 	};
 	if (call.tool !== "edit_file") return call.args;
 	return {
@@ -5934,10 +7742,15 @@ function summarizeToolArgs(call) {
 		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,
@@ -6006,13 +7819,22 @@ function countLogicalLines(content) {
 	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() {
+function getChatSystemPrompt(options = {}) {
+	const profile = options.profile ?? PRIMARY_AGENT_PROFILE;
+	const canUseTool = (toolName) => options.permissions ? isToolAllowed(options.permissions, toolName) : true;
+	const toolPromptLines = options.permissions ? getToolPromptLines((toolName) => canUseTool(toolName)) : getToolPromptLines();
 	return [
 		"You are Topchester, a plain-spoken terminal coding agent for software engineering work.",
 		"Your job is to turn ordinary user requests into concrete repository work: inspect the codebase, make focused changes when tools allow it, verify the result when possible, and report the outcome clearly.",
 		"",
+		`Agent profile: ${profile.displayName} (${profile.id}).`,
+		...profile.promptAdditions,
+		"",
 		"Working style:",
 		"- Start by understanding the user's intent and the surrounding code before proposing or changing anything non-trivial.",
 		"- Prefer local project evidence over assumptions. Use search and read tools to find relevant files, examples, tests, commands, and conventions.",
@@ -6025,67 +7847,281 @@ function getChatSystemPrompt() {
 		"- Ask a clarifying question only when the missing information blocks useful progress or the safe interpretation is genuinely unclear.",
 		"",
 		"You have these tools available:",
-		...getToolPromptLines(),
+		...toolPromptLines,
 		"",
 		"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.",
-		"- 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.",
-		"- 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_hash from read_file.",
-		"- 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.",
+		"- 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.",
+		...canUseTool("plan_todo") ? [
+			"- 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.",
+			"- Do not call plan_todo only to summarize completed work before a final answer. If no visible plan is active and the work is done, answer directly."
+		] : [],
+		...canUseTool("read_file") || canUseTool("grep") || canUseTool("find_file") || canUseTool("list_files") ? ["- Use read/search tools when the user asks about files, code, symbols, usages, tests, or project behavior."] : [],
+		...canUseTool("find_file") && canUseTool("grep") && canUseTool("read_file") ? ["- 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."] : [],
+		...canUseTool("list_files") && canUseTool("grep") && canUseTool("find_file") && canUseTool("read_file") ? ["- Use list_files, grep, find_file, and read_file for exact file listing, search, lookup, and reading tasks."] : [],
+		...canUseTool("git_status") && canUseTool("git_diff") && canUseTool("git_log") ? ["- Use git_status, git_diff, and git_log for Git state, diffs, and history. Prefer these over inspect_command for Git workflow inspection."] : [],
+		...canUseTool("git_add") && canUseTool("git_commit") ? ["- 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."] : [],
+		...canUseTool("inspect_command") ? ["- 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."] : [],
+		...canUseTool("edit_file") && canUseTool("read_file") ? ["- Use read_file before editing a file so your edit is based on current file content and hash metadata."] : [],
+		...canUseTool("read_file") && (canUseTool("edit_file") || canUseTool("write_file")) ? ["- 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."] : [],
+		...canUseTool("edit_file") ? ["- Use edit_file for targeted edits to existing files. Make multiple disjoint edits for the same file in one call when possible."] : [],
+		...canUseTool("write_file") && canUseTool("read_file") ? [
+			"- 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."
+		] : [],
+		...canUseTool("write_file") && !canUseTool("read_file") ? [
+			"- Use write_file to create new files by default. It fails when the file already exists unless overwrite:true is available with verified current content.",
+			"- 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."
+		] : [],
+		...canUseTool("inspect_command") ? ["- Do not use inspect_command for file creation or file mutation."] : [],
+		...canUseTool("edit_file") ? ["- Keep edit_file old_text small but unique. Do not include line labels or grep prefixes in old_text; use exact file text only."] : [],
+		...canUseTool("edit_file") || canUseTool("write_file") ? ["- Use edit/write tools when they are available and the user asks you to implement, fix, add, update, or refactor code."] : [],
+		...canUseTool("inspect_command") ? ["- Use command/test tools when they are available and you need to inspect the environment, run tests, format, lint, typecheck, or verify behavior."] : [],
 		"- After each tool result, decide the next useful action from the new evidence. Continue until the request is handled or blocked.",
 		"Do not make up file contents or search results."
 	].join("\n");
 }
 //#endregion
+//#region src/session/runtime-payloads.ts
+function runtimeEventToSessionPayload(event) {
+	switch (event.type) {
+		case "message": return {
+			kind: "message",
+			role: event.role,
+			text: event.text,
+			...event.meta === void 0 ? {} : { meta: event.meta }
+		};
+		case "tool_call": return {
+			kind: "tool_call",
+			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",
+			tone: event.tone,
+			title: event.title,
+			...event.body === void 0 ? {} : { body: event.body },
+			actions: event.actions
+		};
+		case "subagent_started": return {
+			kind: "subagent_started",
+			sessionId: event.sessionId,
+			parentSessionId: event.parentSessionId,
+			parentToolCallId: event.parentToolCallId,
+			...event.agentProfileId === void 0 ? {} : { agentProfileId: event.agentProfileId },
+			...event.title === void 0 ? {} : { title: event.title }
+		};
+		case "subagent_event": return {
+			kind: "subagent_event",
+			sessionId: event.sessionId,
+			parentSessionId: event.parentSessionId,
+			parentToolCallId: event.parentToolCallId,
+			event: event.event
+		};
+		case "subagent_completed": return {
+			kind: "subagent_completed",
+			sessionId: event.sessionId,
+			parentSessionId: event.parentSessionId,
+			parentToolCallId: event.parentToolCallId,
+			...event.result === void 0 ? {} : { result: event.result }
+		};
+		case "subagent_failed": return {
+			kind: "subagent_failed",
+			sessionId: event.sessionId,
+			parentSessionId: event.parentSessionId,
+			parentToolCallId: event.parentToolCallId,
+			error: event.error
+		};
+		case "status": return {
+			kind: "status",
+			status: event.status
+		};
+	}
+}
+//#endregion
+//#region src/agent/subagents.ts
+var SubagentManager = class {
+	options;
+	constructor(options) {
+		this.options = options;
+	}
+	async runTask(options) {
+		const parentSession = this.options.parentSession;
+		if (!parentSession) throw new Error("task requires an active persisted session.");
+		const profile = resolveAgentProfile(options.subagentType ?? "explore");
+		if (profile.mode !== "subagent" && profile.mode !== "all") throw new Error(`Agent profile "${profile.id}" cannot be used for subagent tasks.`);
+		const child = await createChildSession(this.options.context.workspaceRoot, {
+			parent: parentSession,
+			parentToolCallId: options.parentToolCallId,
+			agentProfileId: profile.id,
+			title: options.description,
+			recordParentEvent: false
+		});
+		const reference = {
+			sessionId: child.sessionId,
+			parentSessionId: parentSession.sessionId,
+			parentToolCallId: options.parentToolCallId
+		};
+		await options.eventSink?.(agentEvent.subagentStarted({
+			...reference,
+			agentProfileId: profile.id,
+			title: options.description
+		}));
+		const childRuntime = this.options.createRuntime({
+			profile,
+			parentPermissions: this.options.parentPermissions,
+			session: child
+		});
+		let finalResponse = "";
+		try {
+			for await (const childEvent of childRuntime.submitMessageStream([], options.prompt, options.abortSignal, { session: child })) {
+				const payload = runtimeEventToSessionPayload(childEvent);
+				if (payload) await child.append(payload);
+				if (childEvent.type === "message" && childEvent.role === "assistant") finalResponse = childEvent.text;
+				await options.eventSink?.(agentEvent.subagentEvent(reference, childEvent));
+			}
+			const result = finalResponse.trim() || "Subagent completed without an assistant response.";
+			await options.eventSink?.(agentEvent.subagentCompleted({
+				...reference,
+				result
+			}));
+			return {
+				sessionId: child.sessionId,
+				status: "completed",
+				result,
+				profileId: profile.id
+			};
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			await options.eventSink?.(agentEvent.subagentFailed({
+				...reference,
+				error: message
+			}));
+			return {
+				sessionId: child.sessionId,
+				status: "failed",
+				result: message,
+				profileId: profile.id
+			};
+		}
+	}
+};
+//#endregion
 //#region src/agent/runtime.ts
-const MAX_TOOL_CALLS_PER_TURN = 8;
-var TopchesterAgentRuntime = class {
+const MAX_TOOL_CALLS_PER_TURN = 75;
+const DEFAULT_TASK_CONCURRENCY = 3;
+var TopchesterAgentRuntime = class TopchesterAgentRuntime {
 	context;
-	constructor(context) {
+	options;
+	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, options = {}) {
 		this.context = context;
+		this.options = options;
 	}
+	/**
+	* 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);
-		const events = [];
-		let nextPrompt = prompt;
+	/**
+	* Streams 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.
+	*
+	* This is the primary runtime execution contract. Compatibility wrappers
+	* can collect the stream, but the runtime's own turn loop only knows about
+	* ordered events.
+	*/
+	async *submitMessageStream(conversation, message, abortSignal, options = {}) {
+		let nextPrompt = await this.buildPromptWithKnowledgeContext(buildConversationPrompt(conversation, message), message);
 		let totalDurationMs = 0;
+		const tokenUsageTotals = {};
+		const profile = this.options.profile ?? PRIMARY_AGENT_PROFILE;
+		const permissions = createToolPermissionView(profile, { deniedTools: this.options.parentPermissions?.deniedTools });
+		const tools = getProfileToolDefinitions(permissions);
+		const session = options.session ?? this.options.session;
+		const subagents = new SubagentManager({
+			context: this.context,
+			parentSession: session,
+			parentProfile: profile,
+			parentPermissions: permissions,
+			createRuntime: ({ profile: childProfile, parentPermissions, session: childSession }) => new TopchesterAgentRuntime(this.context, {
+				...this.options,
+				profile: childProfile,
+				parentPermissions,
+				session: childSession
+			})
+		});
 		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({
+				profile,
+				permissions
+			});
+			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
+				toolProtocol: toolProtocolOverride,
+				onReasoning: options.onReasoning,
+				tools
 			});
 			const durationMs = Date.now() - startedAt;
 			const toolCall = result.toolCalls[0];
 			totalDurationMs += durationMs;
 			lastModelId = result.modelId;
+			addTokenUsageTotals(tokenUsageTotals, result.usage);
 			this.context.logger.debug({
 				event: "model_response",
 				purpose: "agent.primary",
@@ -6093,6 +8129,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,
@@ -6113,25 +8154,120 @@ 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"));
-				return events;
+				const plan = this.taskPlan.get();
+				const finalText = stripSuppressiblePlanTodoPrefix(result.text, plan) ?? result.text;
+				if (hasOpenTaskPlan(plan)) {
+					if (!requestedPlanClosure) {
+						requestedPlanClosure = true;
+						nextPrompt = `${nextPrompt}\n\n${formatOpenPlanClosureInstruction(finalText, result.toolProtocol)}`;
+						continue;
+					}
+					yield agentEvent.taskPlan(this.taskPlan.update({ items: [] }));
+				}
+				yield agentEvent.assistantMessage(finalText.trim() || "I got an empty response from the model.", formatAgentMessageMeta(result.modelId, totalDurationMs, tokenUsageTotals));
+				yield agentEvent.status("ready");
+				return;
 			}
 			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"));
-				return events;
+				yield 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)]
+				});
+				yield agentEvent.status("ready");
+				return;
+			}
+			if (result.toolCalls.length > 1 && result.toolCalls.every((call) => call.tool === "task")) {
+				const taskCalls = result.toolCalls.map((call) => call);
+				const taskResults = [];
+				for (let index = 0; index < taskCalls.length; index += DEFAULT_TASK_CONCURRENCY) {
+					const batch = taskCalls.slice(index, index + DEFAULT_TASK_CONCURRENCY);
+					const taskEventQueue = createRuntimeEventQueue();
+					const batchResultPromise = Promise.all(batch.map((call, batchIndex) => executeToolCall(this.context.workspaceRoot, call, {
+						logger: this.context.logger,
+						taskPlan: this.taskPlan,
+						profile,
+						permissions,
+						subagents,
+						abortSignal,
+						toolCallId: result.toolCalls[index + batchIndex]?.id,
+						eventSink: (event) => taskEventQueue.push(event)
+					}))).finally(() => {
+						taskEventQueue.close();
+					});
+					for await (const event of taskEventQueue) yield event;
+					taskResults.push(...await batchResultPromise);
+				}
+				for (let index = 0; index < taskCalls.length; index += 1) yield agentEvent.toolCall(taskCalls[index], formatToolCallMessage(taskCalls[index], taskResults[index]));
+				afterTool = "task";
+				nextPrompt = `${nextPrompt}\n\n${taskResults.map((toolResult) => formatToolResultForPrompt(toolResult)).join("\n\n")}\n\n${formatContinuationInstruction(result.toolProtocol, taskResults.at(-1), isToolAllowed(permissions, "plan_todo"))}`;
+				continue;
+			}
+			if (result.toolCalls.length > 1 && result.toolCalls.every((call) => isParallelSafeToolName(call.tool))) {
+				const parallelCalls = result.toolCalls.map((call) => call);
+				const parallelResults = await Promise.all(parallelCalls.map((call, index) => executeToolCall(this.context.workspaceRoot, call, {
+					logger: this.context.logger,
+					taskPlan: this.taskPlan,
+					profile,
+					permissions,
+					subagents,
+					abortSignal,
+					toolCallId: result.toolCalls[index]?.id
+				})));
+				for (let index = 0; index < parallelCalls.length; index += 1) yield agentEvent.toolCall(parallelCalls[index], formatToolCallMessage(parallelCalls[index], parallelResults[index]));
+				afterTool = parallelCalls.at(-1)?.tool;
+				nextPrompt = `${nextPrompt}\n\n${parallelResults.map((toolResult) => formatToolResultForPrompt(toolResult)).join("\n\n")}\n\n${formatContinuationInstruction(result.toolProtocol, parallelResults.at(-1), isToolAllowed(permissions, "plan_todo"))}`;
+				continue;
 			}
 			const executableToolCall = toolCall;
-			const toolResult = await executeToolCall(this.context.workspaceRoot, executableToolCall, { logger: this.context.logger });
-			events.push(agentEvent.toolCall(executableToolCall, formatToolCallMessage(executableToolCall, toolResult)));
+			const suppressiblePlanTodoAnswer = getSuppressiblePlanTodoAnswer(executableToolCall, result.text, this.taskPlan.get());
+			if (suppressiblePlanTodoAnswer !== void 0) {
+				yield agentEvent.assistantMessage(suppressiblePlanTodoAnswer || "I got an empty response from the model.", formatAgentMessageMeta(result.modelId, totalDurationMs, tokenUsageTotals));
+				yield agentEvent.status("ready");
+				return;
+			}
+			const toolEventQueue = createRuntimeEventQueue();
+			const toolResultPromise = executeToolCall(this.context.workspaceRoot, executableToolCall, {
+				logger: this.context.logger,
+				taskPlan: this.taskPlan,
+				profile,
+				permissions,
+				subagents,
+				abortSignal,
+				toolCallId: toolCall.id,
+				eventSink: (event) => toolEventQueue.push(event)
+			}).finally(() => {
+				toolEventQueue.close();
+			});
+			for await (const event of toolEventQueue) yield event;
+			const toolResult = await toolResultPromise;
+			yield agentEvent.toolCall(executableToolCall, formatToolCallMessage(executableToolCall, toolResult));
+			if (!isToolErrorResult(toolResult) && toolResult.tool === "plan_todo") yield 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, isToolAllowed(permissions, "plan_todo"))}`;
 		}
-		return [
-			...events,
-			agentEvent.assistantMessage("I stopped because the tool loop ended unexpectedly.", formatAgentMessageMeta(lastModelId, totalDurationMs)),
-			agentEvent.status("ready")
-		];
+		yield agentEvent.assistantMessage("I stopped because the tool loop ended unexpectedly.", formatAgentMessageMeta(lastModelId, totalDurationMs, tokenUsageTotals));
+		yield agentEvent.status("ready");
+	}
+	/**
+	* Compatibility wrapper for callers that still expect a completed event
+	* array or use the older `onEvent` callback shape.
+	*/
+	async submitMessage(conversation, message, abortSignal, onEvent, options = {}) {
+		const events = [];
+		for await (const event of this.submitMessageStream(conversation, message, abortSignal, options)) {
+			events.push(event);
+			await onEvent?.(event);
+		}
+		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,
@@ -6145,6 +8281,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;
@@ -6154,12 +8296,88 @@ 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) {
+		if (this.options.disableL1Context ?? isL1ContextDisabledByEnv()) {
+			this.context.logger.debug({
+				event: "kb_context_pack_skipped",
+				reason: "disabled"
+			}, "kb context pack skipped");
+			return prompt;
+		}
+		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;
+		}
+	}
 };
+function createRuntimeEventQueue() {
+	const events = [];
+	let closed = false;
+	let notify;
+	return {
+		push(event) {
+			events.push(event);
+			notify?.();
+			notify = void 0;
+		},
+		close() {
+			closed = true;
+			notify?.();
+			notify = void 0;
+		},
+		async *[Symbol.asyncIterator]() {
+			while (!closed || events.length > 0) {
+				const event = events.shift();
+				if (event) {
+					yield event;
+					continue;
+				}
+				await new Promise((resolve) => {
+					notify = resolve;
+				});
+			}
+		}
+	};
+}
+/**
+* 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,
-		tools: Object.values(toolRegistry)
-	});
+	if ("generateAgentStep" in context.modelGateway && typeof context.modelGateway.generateAgentStep === "function") return context.modelGateway.generateAgentStep({ ...request });
 	const result = await context.modelGateway.generateText(request);
 	const parsed = parseToolCallWithSource(result.text);
 	const toolProtocol = parsed?.source === "text-xml" ? "text-xml" : "text-json";
@@ -6183,15 +8401,56 @@ async function generateAgentStep(context, request) {
 		openRouterRoutingApplied: false
 	};
 }
+function getSuppressiblePlanTodoAnswer(call, modelText, currentPlan) {
+	if (call.tool !== "plan_todo" || hasOpenTaskPlan(currentPlan)) return;
+	const items = call.args.items;
+	if (!Array.isArray(items) || items.some((item) => !isCompletedPlanTodoItem(item))) return;
+	const parsed = parseToolCallWithSource(modelText, ["text-json"]);
+	return parsed?.remainder ? parsed.remainder : void 0;
+}
+function stripSuppressiblePlanTodoPrefix(modelText, currentPlan) {
+	const parsed = parseToolCallWithSource(modelText, ["text-json"]);
+	if (!parsed) return;
+	return getSuppressiblePlanTodoAnswer(parsed.call, modelText, currentPlan);
+}
+function isCompletedPlanTodoItem(item) {
+	return Boolean(item && typeof item === "object" && "status" in item && item.status === "completed");
+}
+/**
+* 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;
 }
+function isL1ContextDisabledByEnv() {
+	const value = process.env.TOPCHESTER_DISABLE_L1_CONTEXT?.trim().toLowerCase();
+	return value === "1" || value === "true" || value === "yes" || value === "on";
+}
+function shouldShowTokenUsageByEnv() {
+	const value = process.env.TOPCHESTER_SHOW_TOKEN_USAGE?.trim().toLowerCase();
+	return value !== void 0 && value !== "" && value !== "0" && value !== "false" && value !== "no" && value !== "off";
+}
+/**
+* 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" && [
@@ -6202,19 +8461,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}`,
@@ -6222,6 +8506,8 @@ 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 === "task") 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}`,
@@ -6319,11 +8605,50 @@ 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, canUsePlanTodo = true) {
+	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." : "",
+		canUsePlanTodo ? "Update plan_todo after major progress changes." : "",
+		canUsePlanTodo ? "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 "task": return result?.tool === "task" ? `task: ${result.status} ${result.childSessionId}` : `task: ${call.args.description}`;
+		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 ?? "."}`;
@@ -6338,21 +8663,62 @@ function formatToolCallMessage(call, result) {
 		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") return `${result.scope} (${result.fileCount} files${result.truncated ? ", truncated" : ""})`;
+	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") return "";
+	if (result?.tool !== "write_file" || isToolErrorResult(result)) return "";
 	return ` (${result.writeEvent.writeSummary})`;
 }
-function formatAgentMessageMeta(model, durationMs) {
-	return `${model} · ${formatDuration$1(durationMs)}`;
-}
+/**
+* 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, usage) {
+	const tokenUsage = shouldShowTokenUsageByEnv() ? formatTokenUsage(usage) : void 0;
+	return [
+		model,
+		formatDuration$1(durationMs),
+		tokenUsage
+	].filter(Boolean).join(" · ");
+}
+function addTokenUsageTotals(totals, usage) {
+	if (!usage) return;
+	if (typeof usage.inputTokens === "number") totals.inputTokens = (totals.inputTokens ?? 0) + usage.inputTokens;
+	if (typeof usage.outputTokens === "number") totals.outputTokens = (totals.outputTokens ?? 0) + usage.outputTokens;
+}
+function formatTokenUsage(usage) {
+	if (usage?.inputTokens === void 0 && usage?.outputTokens === void 0) return;
+	return `${formatInteger(usage.inputTokens ?? 0)} input / ${formatInteger(usage.outputTokens ?? 0)} output tokens`;
+}
+/**
+* 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`;
@@ -6362,12 +8728,21 @@ 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,
 		maximumFractionDigits: fractionDigits
 	});
 }
+function formatInteger(value) {
+	return value.toLocaleString("en", { maximumFractionDigits: 0 });
+}
 //#endregion
 //#region src/tui/runtime-events.ts
 function renderRuntimeEvent(event) {
@@ -6381,9 +8756,39 @@ function renderRuntimeEvent(event) {
 			body: event.body,
 			actions: event.actions
 		})];
+		case "task_plan": return [];
+		case "subagent_started": return [subagentMessage({
+			status: "running",
+			sessionId: event.sessionId,
+			title: event.title
+		})];
+		case "subagent_event": return formatForwardedSubagentEvent(event.sessionId, event.event);
+		case "subagent_completed": return [subagentMessage({
+			status: "completed",
+			sessionId: event.sessionId,
+			text: event.result
+		})];
+		case "subagent_failed": return [subagentMessage({
+			status: "failed",
+			sessionId: event.sessionId,
+			text: event.error
+		})];
 		case "status": return [];
 	}
 }
+function formatForwardedSubagentEvent(sessionId, event) {
+	if (event.type === "message" && event.role === "assistant") return [subagentMessage({
+		status: "event",
+		sessionId,
+		text: event.text
+	})];
+	if (event.type === "tool_call") return [subagentMessage({
+		status: "event",
+		sessionId,
+		text: event.label
+	})];
+	return [];
+}
 function formatKbPathSource(status) {
 	return status.kbPathSource === "env" ? " (custom)" : "";
 }
@@ -6394,6 +8799,7 @@ var TopchesterTuiShell = class {
 	options;
 	runtime;
 	session;
+	taskPlanNoticeTimer;
 	constructor(context, runtime, options = {}) {
 		this.context = context;
 		this.options = options;
@@ -6410,7 +8816,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();
@@ -6429,11 +8835,12 @@ var TopchesterTuiShell = class {
 				process.exit(0);
 			}
 		});
+		app.setTaskPlan(this.options.initialTaskPlan);
 		app.setSubmitMessage((message) => {
-			this.submitChatMessage(app, tui, message);
+			this.startBackgroundTask(app, tui, "Chat", () => this.submitChatMessage(app, tui, message));
 		});
 		app.setSubmitCommand((command) => {
-			this.submitSlashCommand(app, tui, command);
+			this.startBackgroundTask(app, tui, "Command", () => this.submitSlashCommand(app, tui, command));
 		});
 		tui.addChild(app);
 		tui.setFocus(app);
@@ -6450,7 +8857,15 @@ var TopchesterTuiShell = class {
 			}
 		}));
 		tui.start();
-		this.checkAgent(app, tui);
+		this.startBackgroundTask(app, tui, "Agent check", () => this.checkAgent(app, tui));
+	}
+	startBackgroundTask(app, tui, label, task) {
+		task().catch((error) => {
+			app.addMessage(systemMessage(`${label} failed: ${formatPlainError(error)}`));
+			app.setStatus("ready");
+			app.setCancelPending(void 0);
+			tui.requestRender();
+		});
 	}
 	async checkAgent(app, tui) {
 		const busy = new BusyIndicator(app, tui, {
@@ -6471,13 +8886,13 @@ 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."));
 				app.setStatus("ready");
 			} else {
-				const message = error instanceof Error ? error.message : String(error);
+				const message = formatPlainError(error);
 				app.addMessage(systemMessage(`Agent check failed: ${message}`));
 				app.setStatus("agent check failed");
 			}
@@ -6485,7 +8900,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) {
@@ -6499,6 +8914,7 @@ var TopchesterTuiShell = class {
 			]
 		});
 		const abortController = new AbortController();
+		const reasoningDisplay = isStreamReasoningEnabledByEnv() ? createBusyReasoningSink(busy) : void 0;
 		let cancelled = false;
 		app.setCancelPending(() => {
 			cancelled = true;
@@ -6507,19 +8923,29 @@ 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));
+			for await (const event of this.runtime.submitMessageStream(app.getConversationTurns(), message, abortController.signal, {
+				onReasoning: reasoningDisplay?.sink,
+				session: this.session
+			})) {
+				if (event.type === "message" && event.role === "assistant") {
+					reasoningDisplay?.commit(app);
+					busy.clearActivity();
+				}
+				await this.applyRuntimeEvents(app, [event], tui);
+				tui.requestRender();
+			}
 		} catch (error) {
 			if (cancelled) {
 				app.addMessage(systemMessage("Response stopped."));
 				app.setStatus("ready");
 			} else {
-				const errorMessage = error instanceof Error ? error.message : String(error);
-				app.addMessage(systemMessage(`Chat failed: ${errorMessage}`));
+				app.addMessage(systemMessage(`Chat failed: ${formatPlainError(error)}`));
 				app.setStatus("chat failed");
 				await this.persistPayloadWithWarning(app, {
 					kind: "status",
@@ -6542,13 +8968,13 @@ 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}`));
+			app.addMessage(systemMessage(`Command failed: ${formatPlainError(error)}`));
 			app.setStatus("command failed");
 			await this.persistPayloadWithWarning(app, {
 				kind: "status",
@@ -6559,14 +8985,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 {
@@ -6600,6 +9053,8 @@ function chatMessageToSessionPayload(message) {
 		text: message.text,
 		...message.meta === void 0 ? {} : { meta: message.meta }
 	};
+	if (message.kind === "thinking") return;
+	if (message.kind === "subagent") return;
 	if (message.kind === "modal") return {
 		kind: "choice",
 		tone: message.tone,
@@ -6613,33 +9068,6 @@ function chatMessageToSessionPayload(message) {
 		call: message.call
 	};
 }
-function runtimeEventToSessionPayload(event) {
-	switch (event.type) {
-		case "message": return {
-			kind: "message",
-			role: event.role,
-			text: event.text,
-			...event.meta === void 0 ? {} : { meta: event.meta }
-		};
-		case "tool_call": return {
-			kind: "tool_call",
-			label: event.label,
-			call: event.call
-		};
-		case "knowledge_status": return;
-		case "choice": return {
-			kind: "choice",
-			tone: event.tone,
-			title: event.title,
-			...event.body === void 0 ? {} : { body: event.body },
-			actions: event.actions
-		};
-		case "status": return {
-			kind: "status",
-			status: event.status
-		};
-	}
-}
 function slashCommandToSessionPayload(command) {
 	return {
 		kind: "message",
@@ -6651,8 +9079,34 @@ function slashCommandToSessionPayload(command) {
 		}
 	};
 }
+function isStreamReasoningEnabledByEnv() {
+	const value = process.env.TOPCHESTER_STREAM_REASONING?.trim().toLowerCase();
+	return value === "1" || value === "true" || value === "yes" || value === "on";
+}
+function createBusyReasoningSink(busy) {
+	const buffer = new ReasoningTailBuffer();
+	let committed = false;
+	return {
+		commit(app) {
+			if (committed || !buffer.hasText) return;
+			app.addMessage(thinkingMessage(buffer.value));
+			committed = true;
+		},
+		async sink(event) {
+			if (event.type === "clear") {
+				buffer.clear();
+				committed = false;
+				busy.clearActivity();
+				return;
+			}
+			const text = event.type === "summary" ? buffer.replace(event.text ?? "") : buffer.append(event.text ?? "");
+			if (!text) return;
+			busy.setActivity(ui.muted(text));
+		}
+	};
+}
 function formatPlainError(error) {
-	return error instanceof Error ? error.message : String(error);
+	return (error instanceof Error ? error.message : String(error)).split(/\r?\n/u).map((line) => line.trim()).find((line) => line.length > 0) ?? "Unknown error";
 }
 function printExitBanner(sessionId, durationMs) {
 	console.log("");
@@ -6796,8 +9250,8 @@ async function executeRunCommand(context, options) {
 				text: options.prompt,
 				inputType: "prompt"
 			});
-			await applyRuntimeEvents({
-				events: await runtime.submitMessage(conversation, options.prompt, abortController.signal),
+			for await (const event of runtime.submitMessageStream(conversation, options.prompt, abortController.signal, { session })) await applyRuntimeEvent({
+				event,
 				session,
 				jsonEvents,
 				runId,
@@ -6846,7 +9300,9 @@ async function loadConversation(workspaceRoot, resume) {
 				text: message.text
 			}];
 			case "system":
+			case "thinking":
 			case "tool_call":
+			case "subagent":
 			case "modal": return [];
 		}
 	});
@@ -6858,12 +9314,16 @@ async function persistStartupMessages(session, context) {
 	}
 }
 async function applyRuntimeEvents(options) {
-	for (const event of options.events) {
-		const payload = runtimeEventToSessionPayload(event);
-		if (payload) await options.session.append(payload);
-		pushJson(options.jsonEvents, options.runId, options.session.sessionId, event.type, { event });
-		if (options.plain) printPlainEvent(event);
-	}
+	for (const event of options.events) await applyRuntimeEvent({
+		...options,
+		event
+	});
+}
+async function applyRuntimeEvent(options) {
+	const payload = runtimeEventToSessionPayload(options.event);
+	if (payload) await options.session.append(payload);
+	pushJson(options.jsonEvents, options.runId, options.session.sessionId, options.event.type, { event: options.event });
+	if (options.plain) printPlainEvent(options.event);
 }
 function printPlainEvent(event) {
 	if (event.type === "message") {
@@ -6874,7 +9334,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({
@@ -6906,9 +9373,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;
 		}
@@ -6940,6 +9410,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();
@@ -6973,6 +9446,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) }));
@@ -7019,6 +9498,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";
@@ -7032,6 +9536,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);