topchester-ai 0.4.0 → 0.6.0

package/dist/cli.mjs

@@ -14,7 +14,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { uuidv7 } from "uuidv7";
 import { Input, Markdown, ProcessTerminal, TUI, isKeyRelease, isKeyRepeat, matchesKey, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
 import { highlight, supportsLanguage } from "cli-highlight";
-import { execFile } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
 //#region src/model/index.ts
 var ModelGateway = class {
 	#config;
@@ -131,20 +131,20 @@ const TOPCHESTER_STATE_DIR = ".agents/topchester";
 const TOPCHESTER_SESSIONS_DIR = `${TOPCHESTER_STATE_DIR}/sessions`;
 const TOPCHESTER_LOGS_DIR = `${TOPCHESTER_STATE_DIR}/logs`;
 `${TOPCHESTER_LOGS_DIR}`;
-function resolveWorkspacePath(workspaceRoot, path) {
+function resolveWorkspacePath$1(workspaceRoot, path) {
 	return isAbsolute(path) ? path : resolve(workspaceRoot, path);
 }
 function getTopchesterStatePath(workspaceRoot) {
-	return resolveWorkspacePath(workspaceRoot, TOPCHESTER_STATE_DIR);
+	return resolveWorkspacePath$1(workspaceRoot, TOPCHESTER_STATE_DIR);
 }
 function getTopchesterSessionsPath(workspaceRoot) {
-	return resolveWorkspacePath(workspaceRoot, TOPCHESTER_SESSIONS_DIR);
+	return resolveWorkspacePath$1(workspaceRoot, TOPCHESTER_SESSIONS_DIR);
 }
 function getTopchesterLogsPath(workspaceRoot) {
-	return resolveWorkspacePath(workspaceRoot, TOPCHESTER_LOGS_DIR);
+	return resolveWorkspacePath$1(workspaceRoot, TOPCHESTER_LOGS_DIR);
 }
 function getTopchesterLogFilePath(workspaceRoot, logFile = process.env.TOPCHESTER_LOG_FILE) {
-	return logFile ? resolveWorkspacePath(workspaceRoot, logFile) : join(getTopchesterLogsPath(workspaceRoot), "topchester.log");
+	return logFile ? resolveWorkspacePath$1(workspaceRoot, logFile) : join(getTopchesterLogsPath(workspaceRoot), "topchester.log");
 }
 //#endregion
 //#region src/logging/index.ts
@@ -321,8 +321,8 @@ function shouldUseColor() {
 function getKnowledgeStatus(workspaceRoot) {
 	const kbPathSource = process.env.TOPCHESTER_KB_DIR ? "env" : "default";
 	const cachePathSource = process.env.TOPCHESTER_KB_CACHE_DIR ? "env" : "default";
-	const kbPath = resolveWorkspacePath(workspaceRoot, process.env.TOPCHESTER_KB_DIR ?? "topchester-kb");
-	const cachePath = resolveWorkspacePath(workspaceRoot, process.env.TOPCHESTER_KB_CACHE_DIR ?? ".agents/topchester-kb-cache");
+	const kbPath = resolveWorkspacePath$1(workspaceRoot, process.env.TOPCHESTER_KB_DIR ?? "topchester-kb");
+	const cachePath = resolveWorkspacePath$1(workspaceRoot, process.env.TOPCHESTER_KB_CACHE_DIR ?? ".agents/topchester-kb-cache");
 	const kbStat = safeStat(kbPath);
 	const cacheStat = safeStat(cachePath);
 	return {
@@ -1843,19 +1843,26 @@ function formatKnowledgeStatus(status) {
 	const lines = [
 		"KB status",
 		`workspace: ${status.workspaceRoot}`,
-		`knowledge folder: ${formatPathStatus$2(status.kbPath, status.kbExists, status.kbIsDirectory)} (${status.kbPathSource})`,
-		`local cache folder: ${formatPathStatus$2(status.cachePath, status.cacheExists, status.cacheIsDirectory)} (${status.cachePathSource})`
+		`knowledge folder: ${formatKnowledgePathStatus$2(status)} (${status.kbPathSource})`,
+		`local cache folder: ${formatPathStatus$1(status.cachePath, status.cacheExists, status.cacheIsDirectory)} (${status.cachePathSource})`
 	];
 	if (!status.kbExists) lines.push("state: no knowledge base found yet");
 	else if (!status.kbIsDirectory) lines.push("state: knowledge base path is not a folder");
+	else if (status.kbContentState !== "ready") lines.push("state: knowledge base folder is empty");
 	else lines.push("state: knowledge base found");
 	return lines;
 }
-function formatPathStatus$2(path, exists, isDirectory) {
+function formatPathStatus$1(path, exists, isDirectory) {
 	if (!exists) return `${path} [missing]`;
 	if (!isDirectory) return `${path} [not a folder]`;
 	return `${path} [ok]`;
 }
+function formatKnowledgePathStatus$2(status) {
+	if (!status.kbExists) return `${status.kbPath} [missing]`;
+	if (!status.kbIsDirectory) return `${status.kbPath} [not a folder]`;
+	if (status.kbContentState !== "ready") return `${status.kbPath} [empty]`;
+	return `${status.kbPath} [ok]`;
+}
 //#endregion
 //#region src/tui/markdown.ts
 const codeFenceSentinel = "topchester-code-fence";
@@ -1976,8 +1983,12 @@ function renderSystemMessage(lines) {
 	return [` ${ui.ok("✦")} ${ui.label("System")}:`, ...lines.map((line) => `${bodyPrefix}${formatSystemBodyLine(line)}`)];
 }
 function formatSystemBodyLine(line) {
+	if (isToolCallLine(line)) return ui.muted(line);
 	return line.replace(/\(changed \+\d+\/-\d+\)$/u, (summary) => ui.muted(summary));
 }
+function isToolCallLine(line) {
+	return /^(read_file|list_files|grep|find_file|edit_file|inspect_command): /u.test(line);
+}
 function getPrefix(kind) {
 	switch (kind) {
 		case "agent": return " ";
@@ -2058,6 +2069,48 @@ function escapeRegex(value) {
 	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 //#endregion
+//#region src/tui/prompt-history.ts
+const DEFAULT_MAX_PROMPTS = 100;
+var PromptHistory = class {
+	maxPrompts;
+	prompts = [];
+	historyIndex = -1;
+	draft = "";
+	constructor(maxPrompts = DEFAULT_MAX_PROMPTS) {
+		this.maxPrompts = Math.max(1, maxPrompts);
+	}
+	add(value) {
+		const prompt = value.trim();
+		this.resetBrowsing();
+		if (prompt.length === 0 || prompt === this.prompts[0]) return;
+		this.prompts.unshift(prompt);
+		this.prompts = this.prompts.slice(0, this.maxPrompts);
+	}
+	previous(currentDraft) {
+		if (this.prompts.length === 0) return;
+		if (this.historyIndex === -1) {
+			this.draft = currentDraft;
+			this.historyIndex = 0;
+			return this.prompts[this.historyIndex];
+		}
+		this.historyIndex = Math.min(this.historyIndex + 1, this.prompts.length - 1);
+		return this.prompts[this.historyIndex];
+	}
+	next() {
+		if (this.historyIndex === -1) return;
+		if (this.historyIndex === 0) {
+			this.historyIndex = -1;
+			return this.draft;
+		}
+		this.historyIndex -= 1;
+		return this.prompts[this.historyIndex];
+	}
+	resetBrowsing() {
+		this.historyIndex = -1;
+		this.draft = "";
+	}
+};
+//#endregion
 //#region src/tui/status.ts
 function getStartupThreadMessages(context) {
 	const assignments = context.config.models?.assignments ?? {};
@@ -2136,10 +2189,17 @@ function formatKnowledgeFooterStatus(status) {
 	if (status.kbContentState !== "ready") return `${ui.label("○")} kb: ${ui.label("empty")}`;
 	return `${ui.ok("✅")} kb: ${ui.ok("ready")}`;
 }
-function formatPathStatus$1(path, exists, isDirectory) {
-	if (!exists) return `${path} ${ui.warn("[missing]")}`;
-	if (!isDirectory) return `${path} ${ui.error("[not a folder]")}`;
-	return `${path} ${ui.ok("[ok]")}`;
+function formatKnowledgePathStatus$1(status) {
+	const pathLabel = `${ui.label("")} ${formatWorkspaceRelativePath(status.kbPath, status.workspaceRoot)}`;
+	if (!status.kbExists) return `${pathLabel} ${ui.warn("[missing]")}`;
+	if (!status.kbIsDirectory) return `${pathLabel} ${ui.error("[not a folder]")}`;
+	if (status.kbContentState !== "ready") return `${pathLabel} ${ui.label("[empty]")}`;
+	return `${pathLabel} ${ui.ok("[ok]")}`;
+}
+function formatWorkspaceRelativePath(path, workspaceRoot) {
+	const relativePath = relative(workspaceRoot, path);
+	if (relativePath && !relativePath.startsWith("..") && !isAbsolute(relativePath)) return relativePath;
+	return path;
 }
 function getModelLabel(context) {
 	const purpose = context.config.models?.defaultPurpose ?? "agent.primary";
@@ -2188,6 +2248,7 @@ var ChatLayout = class {
 	activeModalActionIndex = 0;
 	activeSlashSuggestionIndex = 0;
 	threadScrollOffset = 0;
+	promptHistory = new PromptHistory();
 	constructor(terminal, messages, folderName, modelLabel, exitAgent = () => {}) {
 		this.terminal = terminal;
 		this.messages = messages;
@@ -2264,8 +2325,11 @@ var ChatLayout = class {
 		}
 		if (this.handleModalInput(data)) return;
 		if (this.handleSlashSuggestionInput(data)) return;
+		if (this.handlePromptHistoryInput(data)) return;
 		if (this.handleThreadScrollInput(data)) return;
+		const previousInput = this.input.getValue();
 		this.input.handleInput(data);
+		if (this.input.getValue() !== previousInput) this.promptHistory.resetBrowsing();
 	}
 	invalidate() {
 		this.input.invalidate();
@@ -2377,14 +2441,6 @@ var ChatLayout = class {
 	handleThreadScrollInput(data) {
 		const pageSize = Math.max(1, Math.floor(this.terminal.rows / 2));
 		const wheel = parseMouseWheel(data);
-		if (isUpKey(data)) {
-			this.threadScrollOffset += 3;
-			return true;
-		}
-		if (isDownKey(data)) {
-			this.threadScrollOffset = Math.max(0, this.threadScrollOffset - 3);
-			return true;
-		}
 		if (wheel === "up") {
 			this.threadScrollOffset += 3;
 			return true;
@@ -2411,6 +2467,20 @@ var ChatLayout = class {
 		}
 		return false;
 	}
+	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);
+			return true;
+		}
+		if (isDownKey(data)) {
+			const prompt = this.promptHistory.next();
+			if (prompt !== void 0) this.input.setValue(prompt);
+			return true;
+		}
+		return false;
+	}
 	handleSlashSuggestionInput(data) {
 		const suggestions = this.getSlashSuggestions();
 		if (suggestions.length === 0) {
@@ -2438,6 +2508,7 @@ var ChatLayout = class {
 	completeSlashSuggestion(suggestions) {
 		this.input.setValue(suggestions[this.activeSlashSuggestionIndex]?.value ?? this.input.getValue());
 		this.input.handleInput("\x1B[F");
+		this.promptHistory.resetBrowsing();
 	}
 	getSlashSuggestions() {
 		return getSlashCommandSuggestions(this.input.getValue());
@@ -2453,6 +2524,7 @@ var ChatLayout = class {
 		this.submitUserInput(message);
 	}
 	submitUserInput(message) {
+		this.promptHistory.add(message);
 		if (message.startsWith("/")) this.submitCommand?.(message);
 		else this.submitMessage?.(message);
 	}
@@ -2985,7 +3057,7 @@ async function collectWorkspaceFilesWithNode(workspaceRoot, startPath) {
 	return files;
 }
 async function createRipgrepCollector(pathEnv, relativeStartPath) {
-	const command = await findExecutable$1("rg", pathEnv);
+	const command = await findExecutable$2("rg", pathEnv);
 	if (!command) return;
 	return {
 		name: "rg",
@@ -3001,8 +3073,8 @@ async function createRipgrepCollector(pathEnv, relativeStartPath) {
 	};
 }
 async function createFdCollector(pathEnv, relativeStartPath) {
-	const fdCommand = await findExecutable$1("fd", pathEnv);
-	const fdfindCommand = fdCommand ? void 0 : await findExecutable$1("fdfind", pathEnv);
+	const fdCommand = await findExecutable$2("fd", pathEnv);
+	const fdfindCommand = fdCommand ? void 0 : await findExecutable$2("fdfind", pathEnv);
 	const command = fdCommand ?? fdfindCommand;
 	if (!command) return;
 	return {
@@ -3022,7 +3094,7 @@ async function createFdCollector(pathEnv, relativeStartPath) {
 	};
 }
 async function createFindCollector(pathEnv, relativeStartPath) {
-	const command = await findExecutable$1("find", pathEnv);
+	const command = await findExecutable$2("find", pathEnv);
 	if (!command) return;
 	return {
 		name: "find",
@@ -3117,7 +3189,7 @@ function resolveWorkspaceScopedPath$2(workspaceRoot, path) {
 		relativePath: relativePath || "."
 	};
 }
-async function findExecutable$1(name, pathEnv) {
+async function findExecutable$2(name, pathEnv) {
 	for (const pathEntry of pathEnv.split(delimiter).filter(Boolean)) {
 		const executablePath = join(pathEntry, name);
 		try {
@@ -3241,14 +3313,14 @@ function resolveWorkspaceScopedPath$1(workspaceRoot, path) {
 }
 async function findSearchExecutable(pathEnv = process.env.PATH ?? "") {
 	for (const name of ["rg", "grep"]) {
-		const executablePath = await findExecutable(name, pathEnv);
+		const executablePath = await findExecutable$1(name, pathEnv);
 		if (executablePath) return {
 			name,
 			path: executablePath
 		};
 	}
 }
-async function findExecutable(name, pathEnv) {
+async function findExecutable$1(name, pathEnv) {
 	for (const pathEntry of pathEnv.split(delimiter).filter(Boolean)) {
 		const executablePath = join(pathEntry, name);
 		try {
@@ -3286,6 +3358,758 @@ function truncateToolOutput(output) {
 function isRecord$1(value) {
 	return typeof value === "object" && value !== null;
 }
+//#endregion
+//#region src/agent/tools/inspect-command-parser.ts
+const REJECTED_SYNTAX = [
+	[/\r|\n/, "multiline commands are not allowed"],
+	[/[<>]/, "redirects are not allowed"],
+	[/\|&/, "stderr pipelines are not allowed"],
+	[/\$\(|\$\{|\$/, "shell expansion is not allowed"],
+	[/`/, "command substitution is not allowed"],
+	[/[()]/, "subshells are not allowed"],
+	[/[{}]/, "command groups are not allowed"],
+	[/\*/, "globs are not allowed"],
+	[/\?/, "globs are not allowed"],
+	[/\[/, "globs are not allowed"],
+	[/\]/, "globs are not allowed"]
+];
+function parseInspectCommand(command) {
+	const trimmed = command.trim();
+	if (!trimmed) throw new Error("inspect_command requires a command.");
+	for (const [pattern, reason] of REJECTED_SYNTAX) if (pattern.test(trimmed)) throw new Error(`inspect_command rejected this command because ${reason}.`);
+	const tokens = tokenize(trimmed);
+	if (tokens.length === 0) throw new Error("inspect_command requires a command.");
+	return {
+		command: trimmed,
+		entries: parseCommandList(tokens)
+	};
+}
+function tokenize(command) {
+	const tokens = [];
+	let index = 0;
+	while (index < command.length) {
+		const char = command[index];
+		if (/\s/.test(char)) {
+			index += 1;
+			continue;
+		}
+		if (command.startsWith("&&", index) || command.startsWith("||", index)) {
+			tokens.push({
+				type: "operator",
+				value: command.slice(index, index + 2)
+			});
+			index += 2;
+			continue;
+		}
+		if (char === "|" || char === ";") {
+			tokens.push({
+				type: "operator",
+				value: char
+			});
+			index += 1;
+			continue;
+		}
+		if (char === "&") throw new Error("inspect_command rejected this command because background jobs are not allowed.");
+		const word = readWord(command, index);
+		tokens.push({
+			type: "word",
+			value: word.value
+		});
+		index = word.nextIndex;
+	}
+	return tokens;
+}
+function readWord(command, startIndex) {
+	let index = startIndex;
+	let value = "";
+	while (index < command.length) {
+		const char = command[index];
+		if (/\s/.test(char) || char === "|" || char === ";" || char === "&") break;
+		if (char === "'") {
+			const quoted = readQuotedWord(command, index + 1, "'");
+			value += quoted.value;
+			index = quoted.nextIndex;
+			continue;
+		}
+		if (char === "\"") {
+			const quoted = readQuotedWord(command, index + 1, "\"");
+			value += quoted.value;
+			index = quoted.nextIndex;
+			continue;
+		}
+		value += char;
+		index += 1;
+	}
+	if (!value) throw new Error("inspect_command rejected this command because empty words are not allowed.");
+	return {
+		value,
+		nextIndex: index
+	};
+}
+function readQuotedWord(command, startIndex, quote) {
+	let index = startIndex;
+	let value = "";
+	while (index < command.length) {
+		const char = command[index];
+		if (char === quote) return {
+			value,
+			nextIndex: index + 1
+		};
+		value += char;
+		index += 1;
+	}
+	throw new Error("inspect_command rejected this command because quoted strings must be closed.");
+}
+function parseCommandList(tokens) {
+	const entries = [];
+	let index = 0;
+	let operator = "start";
+	while (index < tokens.length) {
+		if (tokens[index]?.type === "operator") throw new Error("inspect_command rejected this command because operators must appear between commands.");
+		const parsed = parsePipeline(tokens, index);
+		entries.push({
+			operator,
+			pipeline: parsed.pipeline
+		});
+		index = parsed.nextIndex;
+		if (index >= tokens.length) break;
+		const token = tokens[index];
+		if (token?.type !== "operator" || token.value === "|") throw new Error("inspect_command rejected this command because pipelines must contain commands on both sides.");
+		operator = token.value;
+		index += 1;
+		if (index >= tokens.length) throw new Error("inspect_command rejected this command because operators must appear between commands.");
+	}
+	return entries;
+}
+function parsePipeline(tokens, startIndex) {
+	const commands = [];
+	let index = startIndex;
+	while (index < tokens.length) {
+		const parsed = parseSimpleCommand(tokens, index);
+		commands.push(parsed.command);
+		index = parsed.nextIndex;
+		const token = tokens[index];
+		if (token?.type !== "operator" || token.value !== "|") break;
+		index += 1;
+		if (index >= tokens.length || tokens[index]?.type === "operator") throw new Error("inspect_command rejected this command because pipelines must contain commands on both sides.");
+	}
+	return {
+		pipeline: { commands },
+		nextIndex: index
+	};
+}
+function parseSimpleCommand(tokens, startIndex) {
+	const words = [];
+	let index = startIndex;
+	while (index < tokens.length) {
+		const token = tokens[index];
+		if (token?.type !== "word") break;
+		words.push(token.value);
+		index += 1;
+	}
+	if (words.length === 0) throw new Error("inspect_command rejected this command because empty commands are not allowed.");
+	return {
+		command: {
+			executable: words[0] ?? "",
+			args: words.slice(1)
+		},
+		nextIndex: index
+	};
+}
+//#endregion
+//#region src/agent/tools/inspect-command-policy.ts
+const inspectCommandArgsSchema = z.object({
+	command: z.string().min(1).max(2e3),
+	workdir: z.string().optional().default("."),
+	timeout_ms: z.number().int().min(100).max(1e4).optional().default(1e4)
+});
+const READ_ONLY_COMMANDS = new Set([
+	"pwd",
+	"ls",
+	"rg",
+	"grep",
+	"find",
+	"fd",
+	"cat",
+	"head",
+	"tail",
+	"wc",
+	"stat",
+	"file",
+	"du",
+	"git"
+]);
+const PATHLESS_GIT_SUBCOMMANDS = new Set([
+	"status",
+	"log",
+	"diff",
+	"show",
+	"branch",
+	"rev-parse",
+	"ls-files"
+]);
+const GIT_OPTIONS_WITH_PATH_VALUES = new Set(["--", "--pathspec-from-file"]);
+const COMMON_OPTIONS_WITH_VALUES = new Set([
+	"-A",
+	"-B",
+	"-C",
+	"-c",
+	"-e",
+	"-m",
+	"-n",
+	"-S",
+	"-s",
+	"--after-context",
+	"--before-context",
+	"--color",
+	"--context",
+	"--encoding",
+	"--glob",
+	"--heading",
+	"--ignore-file",
+	"--max-count",
+	"--max-depth",
+	"--max-filesize",
+	"--sort",
+	"--sort-files",
+	"--type",
+	"--type-add"
+]);
+const FIND_OPTIONS_WITH_VALUES = new Set([
+	"-name",
+	"-iname",
+	"-path",
+	"-ipath",
+	"-type",
+	"-maxdepth",
+	"-mindepth",
+	"-size",
+	"-mtime",
+	"-newer"
+]);
+const FD_OPTIONS_WITH_VALUES = new Set([
+	"-e",
+	"-t",
+	"-d",
+	"--extension",
+	"--type",
+	"--max-depth",
+	"--min-depth"
+]);
+const SAFE_PATHLESS_FLAGS = new Set([
+	"--",
+	"-0",
+	"-1",
+	"-a",
+	"-A",
+	"-B",
+	"-C",
+	"-F",
+	"-G",
+	"-H",
+	"-L",
+	"-R",
+	"-S",
+	"-a",
+	"-b",
+	"-c",
+	"-d",
+	"-f",
+	"-g",
+	"-h",
+	"-i",
+	"-l",
+	"-m",
+	"-n",
+	"-p",
+	"-r",
+	"-s",
+	"-t",
+	"-u",
+	"-v",
+	"-w",
+	"-x",
+	"--all",
+	"--brief",
+	"--bytes",
+	"--color",
+	"--count",
+	"--dereference",
+	"--files",
+	"--follow",
+	"--heading",
+	"--hidden",
+	"--ignore-case",
+	"--line-number",
+	"--long",
+	"--max-depth",
+	"--no-heading",
+	"--no-ignore",
+	"--null",
+	"--oneline",
+	"--print",
+	"--recursive",
+	"--short",
+	"--show-current",
+	"--show-toplevel",
+	"--sort",
+	"--word-regexp"
+]);
+const DENIED_FLAGS = new Set([
+	"--hostname-bin",
+	"--pre",
+	"--pre-glob",
+	"--search-zip",
+	"-z",
+	"-Z",
+	"-delete",
+	"-exec",
+	"-execdir",
+	"-ok",
+	"-okdir",
+	"-fls",
+	"-fprintf",
+	"-fprint",
+	"--exec",
+	"-x",
+	"--exec-batch",
+	"-X"
+]);
+function validateInspectCommand(args, context) {
+	let plan;
+	try {
+		plan = parseInspectCommand(args.command);
+	} catch (error) {
+		return {
+			allowed: false,
+			reason: error instanceof Error ? error.message : "inspect_command rejected this command.",
+			commands: []
+		};
+	}
+	const commands = plan.entries.flatMap((entry) => entry.pipeline.commands.map(formatSimpleCommand));
+	const workspace = resolve(context.workspaceRoot);
+	const workdir = resolveWorkspacePath(workspace, context.workdir ?? args.workdir);
+	if (!workdir.allowed) return {
+		allowed: false,
+		reason: workdir.reason,
+		commands,
+		plan
+	};
+	for (const command of plan.entries.flatMap((entry) => entry.pipeline.commands)) {
+		const result = validateSimpleCommand(command, {
+			workspaceRoot: workspace,
+			cwd: workdir.path
+		});
+		if (!result.allowed) return {
+			allowed: false,
+			reason: result.reason,
+			commands,
+			plan
+		};
+	}
+	return {
+		allowed: true,
+		reason: "command uses the inspect_command read-only allowlist",
+		commands,
+		plan
+	};
+}
+function validateSimpleCommand(command, context) {
+	if (command.executable.includes("/") || command.executable === "cd") return {
+		allowed: false,
+		reason: `inspect_command rejected '${command.executable}' because it is not allowed.`
+	};
+	if (!READ_ONLY_COMMANDS.has(command.executable)) return {
+		allowed: false,
+		reason: `inspect_command rejected '${command.executable}' because it is not allowed.`
+	};
+	if (command.args.some((arg) => DENIED_FLAGS.has(arg))) {
+		const flag = command.args.find((arg) => DENIED_FLAGS.has(arg));
+		return {
+			allowed: false,
+			reason: `inspect_command rejected '${command.executable}' because '${flag}' is unsafe.`
+		};
+	}
+	switch (command.executable) {
+		case "pwd": return command.args.length === 0 ? { allowed: true } : {
+			allowed: false,
+			reason: "inspect_command rejected 'pwd' because it does not accept path arguments."
+		};
+		case "git": return validateGitCommand(command, context);
+		case "find": return validateFindCommand(command, context);
+		case "fd": return validateGenericCommandArgs(command, context, FD_OPTIONS_WITH_VALUES);
+		default: return validateGenericCommandArgs(command, context, COMMON_OPTIONS_WITH_VALUES);
+	}
+}
+function validateGitCommand(command, context) {
+	const subcommand = command.args.find((arg) => !arg.startsWith("-"));
+	if (!subcommand || !PATHLESS_GIT_SUBCOMMANDS.has(subcommand)) return {
+		allowed: false,
+		reason: "inspect_command rejected 'git' because only read-only git subcommands are allowed."
+	};
+	if (subcommand === "branch" && command.args.some((arg) => arg !== "branch" && arg !== "--show-current")) return {
+		allowed: false,
+		reason: "inspect_command rejected 'git branch' because only --show-current is allowed."
+	};
+	if (subcommand === "rev-parse" && command.args.some((arg) => arg !== "rev-parse" && arg !== "--show-toplevel")) return {
+		allowed: false,
+		reason: "inspect_command rejected 'git rev-parse' because only --show-toplevel is allowed."
+	};
+	return validateGenericCommandArgs(command, context, GIT_OPTIONS_WITH_PATH_VALUES, new Set(["git", subcommand]));
+}
+function validateFindCommand(command, context) {
+	return validateGenericCommandArgs(command, context, FIND_OPTIONS_WITH_VALUES);
+}
+function validateGenericCommandArgs(command, context, optionsWithValues, knownPathlessWords = /* @__PURE__ */ new Set()) {
+	for (let index = 0; index < command.args.length; index += 1) {
+		const arg = command.args[index] ?? "";
+		if (knownPathlessWords.has(arg)) continue;
+		if (optionsWithValues.has(arg)) {
+			index += 1;
+			continue;
+		}
+		if (arg.startsWith("--") && arg.includes("=")) {
+			const [flag, value] = arg.split("=", 2);
+			if (DENIED_FLAGS.has(flag ?? "")) return {
+				allowed: false,
+				reason: `inspect_command rejected '${command.executable}' because '${flag}' is unsafe.`
+			};
+			if (looksLikePath(value ?? "")) {
+				const scoped = resolveWorkspacePath(context.workspaceRoot, value ?? "", context.cwd);
+				if (!scoped.allowed) return {
+					allowed: false,
+					reason: scoped.reason
+				};
+			}
+			continue;
+		}
+		if (arg.startsWith("-")) {
+			if (SAFE_PATHLESS_FLAGS.has(arg) || /^-[A-Za-z0-9]+$/.test(arg)) continue;
+			return {
+				allowed: false,
+				reason: `inspect_command rejected '${command.executable}' because '${arg}' is not allowed.`
+			};
+		}
+		if (!looksLikePath(arg)) continue;
+		const scoped = resolveWorkspacePath(context.workspaceRoot, arg, context.cwd);
+		if (!scoped.allowed) return {
+			allowed: false,
+			reason: scoped.reason
+		};
+	}
+	return { allowed: true };
+}
+function resolveWorkspacePath(workspaceRoot, path, cwd = workspaceRoot) {
+	const resolved = isAbsolute(path) ? resolve(path) : resolve(cwd, path);
+	const relativePath = relative(workspaceRoot, resolved);
+	if (relativePath.startsWith("..") || isAbsolute(relativePath)) return {
+		allowed: false,
+		reason: `inspect_command rejected path outside the workspace: ${path}`
+	};
+	return {
+		allowed: true,
+		path: resolved
+	};
+}
+function looksLikePath(arg) {
+	return arg === "." || arg === ".." || arg.startsWith("./") || arg.startsWith("../") || arg.startsWith("/") || arg.includes("/");
+}
+function formatSimpleCommand(command) {
+	return [command.executable, ...command.args].join(" ");
+}
+//#endregion
+//#region src/agent/tools/inspect-command.ts
+const MAX_OUTPUT_BYTES = 4e4;
+const MAX_OUTPUT_LINES = 1e3;
+const inspectCommandTool = defineTool({
+	name: "inspect_command",
+	description: "Run a narrowly validated read-only command for repository orientation.",
+	prompt: "inspect_command: run a safe read-only discovery command inside the workspace for quick orientation; prefer read_file, list_files, grep, and find_file for exact file tasks, and do not use it for builds, tests, installs, network, shell scripts, or edits. To use it, reply with only JSON: {\"tool\":\"inspect_command\",\"args\":{\"command\":\"pwd && rg --files docs/plans | head -20\",\"workdir\":\".\",\"timeout_ms\":10000}}",
+	argsSchema: inspectCommandArgsSchema,
+	execute: (context, args) => inspectWorkspaceCommand(context.workspaceRoot, args, { pathEnv: context.pathEnv })
+});
+async function inspectWorkspaceCommand(workspaceRoot, args, options = {}) {
+	const startedAt = Date.now();
+	const decision = validateInspectCommand(args, { workspaceRoot });
+	if (!decision.allowed) throw new Error(decision.reason);
+	const resolvedWorkspace = await realpath(resolve(workspaceRoot));
+	const cwd = await resolveWorkspaceCwd(resolvedWorkspace, args.workdir);
+	const deadlineAt = startedAt + args.timeout_ms;
+	const result = await executePlan(decision.plan, {
+		cwd,
+		pathEnv: options.pathEnv ?? process.env.PATH ?? "",
+		deadlineAt
+	});
+	const durationMs = Date.now() - startedAt;
+	return {
+		tool: "inspect_command",
+		command: args.command,
+		cwd: relative(resolvedWorkspace, cwd) || ".",
+		content: formatInspectCommandContent(result),
+		exitCode: result.exitCode,
+		durationMs,
+		timedOut: result.timedOut,
+		truncated: result.truncated,
+		warning: result.missingExecutable ? `inspect_command could not run because '${result.missingExecutable}' is not available on PATH.` : result.timedOut ? "inspect_command timed out." : result.truncated ? "inspect_command output was truncated." : void 0,
+		decision: {
+			allowed: true,
+			reason: decision.reason,
+			commands: decision.commands
+		},
+		stdout: result.stdout,
+		stderr: result.stderr
+	};
+}
+async function executePlan(plan, context) {
+	let lastExitCode = 0;
+	let stdout = "";
+	let stderr = "";
+	let timedOut = false;
+	let truncated = false;
+	for (const entry of plan.entries) {
+		if (!shouldExecuteEntry(entry, lastExitCode)) continue;
+		const remainingMs = getRemainingTimeoutMs(context.deadlineAt);
+		if (remainingMs <= 0) return {
+			stdout,
+			stderr,
+			exitCode: lastExitCode,
+			timedOut: true,
+			truncated
+		};
+		const result = await executePipeline(entry.pipeline, {
+			...context,
+			timeoutMs: remainingMs
+		});
+		stdout = appendBoundedOutput(stdout, result.stdout).output;
+		const nextStderr = appendBoundedOutput(stderr, result.stderr);
+		stderr = nextStderr.output;
+		truncated = truncated || result.truncated || nextStderr.truncated;
+		timedOut = timedOut || result.timedOut;
+		lastExitCode = result.exitCode;
+		if (result.missingExecutable || result.timedOut) return {
+			stdout,
+			stderr,
+			exitCode: result.exitCode,
+			timedOut,
+			truncated,
+			missingExecutable: result.missingExecutable
+		};
+	}
+	return {
+		stdout,
+		stderr,
+		exitCode: lastExitCode,
+		timedOut,
+		truncated
+	};
+}
+async function executePipeline(pipeline, context) {
+	let input = "";
+	let stderr = "";
+	let exitCode = 0;
+	let timedOut = false;
+	let truncated = false;
+	for (const command of pipeline.commands) {
+		const remainingMs = getRemainingTimeoutMs(context.deadlineAt);
+		if (remainingMs <= 0) return {
+			stdout: input,
+			stderr,
+			exitCode,
+			timedOut: true,
+			truncated
+		};
+		const result = await executeSimpleCommand(command, input, {
+			...context,
+			timeoutMs: remainingMs
+		});
+		input = result.stdout;
+		const nextStderr = appendBoundedOutput(stderr, result.stderr);
+		stderr = nextStderr.output;
+		exitCode = result.exitCode;
+		timedOut = timedOut || result.timedOut;
+		truncated = truncated || result.truncated || nextStderr.truncated;
+		if (result.missingExecutable || result.timedOut || result.exitCode !== 0) return {
+			stdout: input,
+			stderr,
+			exitCode,
+			timedOut,
+			truncated,
+			missingExecutable: result.missingExecutable
+		};
+	}
+	return {
+		stdout: input,
+		stderr,
+		exitCode,
+		timedOut,
+		truncated
+	};
+}
+async function executeSimpleCommand(command, input, context) {
+	if (command.executable === "pwd") return {
+		stdout: `${context.cwd}\n`,
+		stderr: "",
+		exitCode: 0,
+		timedOut: false,
+		truncated: false
+	};
+	const executablePath = await findExecutable(command.executable, context.pathEnv);
+	if (!executablePath) return {
+		stdout: "",
+		stderr: `inspect_command could not run because '${command.executable}' is not available on PATH.\n`,
+		exitCode: 127,
+		timedOut: false,
+		truncated: false,
+		missingExecutable: command.executable
+	};
+	return runSpawnedCommand(executablePath, command.args, input, context);
+}
+function runSpawnedCommand(command, args, input, context) {
+	return new Promise((resolveCommand) => {
+		const detached = process.platform !== "win32";
+		const child = spawn(command, args, {
+			cwd: context.cwd,
+			detached,
+			env: {
+				...process.env,
+				PATH: context.pathEnv,
+				PAGER: "cat",
+				GIT_PAGER: "cat",
+				LESS: "-F -X"
+			},
+			stdio: [
+				input.length > 0 ? "pipe" : "ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		let stdout = "";
+		let stderr = "";
+		let truncated = false;
+		let settled = false;
+		let timedOut = false;
+		const timeout = setTimeout(() => {
+			timedOut = true;
+			killChild(child.pid, detached, "SIGTERM");
+			setTimeout(() => {
+				if (!settled) killChild(child.pid, detached, "SIGKILL");
+			}, 250).unref();
+		}, context.timeoutMs);
+		child.stdout?.on("data", (chunk) => {
+			const next = appendBoundedOutput(stdout, stripUnsafeControlCharacters(chunk.toString("utf8")));
+			stdout = next.output;
+			truncated = truncated || next.truncated;
+		});
+		child.stderr?.on("data", (chunk) => {
+			const next = appendBoundedOutput(stderr, stripUnsafeControlCharacters(chunk.toString("utf8")));
+			stderr = next.output;
+			truncated = truncated || next.truncated;
+		});
+		child.on("error", (error) => {
+			clearTimeout(timeout);
+			settled = true;
+			resolveCommand({
+				stdout,
+				stderr: stderr || `${error.message}\n`,
+				exitCode: 1,
+				timedOut,
+				truncated
+			});
+		});
+		child.on("close", (code, signal) => {
+			clearTimeout(timeout);
+			settled = true;
+			resolveCommand({
+				stdout,
+				stderr,
+				exitCode: timedOut ? 124 : code ?? (signal ? 1 : 0),
+				timedOut,
+				truncated
+			});
+		});
+		if (child.stdin) {
+			child.stdin.on("error", (error) => {
+				if (error.code !== "EPIPE") {
+					const next = appendBoundedOutput(stderr, `${error.message}\n`);
+					stderr = next.output;
+					truncated = truncated || next.truncated;
+				}
+			});
+			child.stdin.end(input);
+		}
+	});
+}
+function killChild(pid, detached, signal) {
+	if (pid === void 0) return;
+	try {
+		process.kill(detached ? -pid : pid, signal);
+	} catch {
+		try {
+			process.kill(pid, signal);
+		} catch {}
+	}
+}
+async function resolveWorkspaceCwd(workspaceRoot, workdir) {
+	const resolvedCwd = resolve(workspaceRoot, workdir);
+	if (!(await stat(resolvedCwd)).isDirectory()) throw new Error(`inspect_command workdir must be a directory inside the workspace: ${workdir}`);
+	const realCwd = await realpath(resolvedCwd);
+	const relativePath = relative(workspaceRoot, realCwd);
+	if (relativePath.startsWith("..") || isAbsolute(relativePath)) throw new Error(`inspect_command rejected path outside the workspace: ${workdir}`);
+	return realCwd;
+}
+async function findExecutable(name, pathEnv) {
+	for (const pathEntry of pathEnv.split(delimiter).filter(Boolean)) {
+		const executablePath = join(pathEntry, name);
+		try {
+			await access(executablePath, constants.X_OK);
+			return executablePath;
+		} catch {
+			continue;
+		}
+	}
+}
+function shouldExecuteEntry(entry, previousExitCode) {
+	switch (entry.operator) {
+		case "start":
+		case ";": return true;
+		case "&&": return previousExitCode === 0;
+		case "||": return previousExitCode !== 0;
+	}
+}
+function getRemainingTimeoutMs(deadlineAt) {
+	return deadlineAt - Date.now();
+}
+function formatInspectCommandContent(result) {
+	const sections = [];
+	sections.push(result.stdout.trimEnd() || "(no output)");
+	if (result.stderr.trim()) sections.push(["stderr:", result.stderr.trimEnd()].join("\n"));
+	sections.push([
+		"metadata:",
+		`exit_code: ${result.exitCode}`,
+		`timed_out: ${result.timedOut}`,
+		`truncated: ${result.truncated}`
+	].join("\n"));
+	return sections.join("\n\n");
+}
+function appendBoundedOutput(current, next) {
+	const combined = current + next;
+	const byteLimited = Buffer.byteLength(combined, "utf8") > MAX_OUTPUT_BYTES;
+	const lineLimited = combined.split("\n").length > MAX_OUTPUT_LINES;
+	if (!byteLimited && !lineLimited) return {
+		output: combined,
+		truncated: false
+	};
+	let output = combined;
+	if (byteLimited) output = output.slice(0, MAX_OUTPUT_BYTES);
+	if (lineLimited) output = output.split("\n").slice(0, MAX_OUTPUT_LINES).join("\n");
+	return {
+		output: `${output.trimEnd()}\n[truncated]\n`,
+		truncated: true
+	};
+}
+function stripUnsafeControlCharacters(output) {
+	return output.replace(/[^\t\n\r -~]/g, "");
+}
 const listFilesTool = defineTool({
 	name: "list_files",
 	description: "List files and directories inside a workspace folder.",
@@ -3401,7 +4225,8 @@ const toolRegistry = {
 	[listFilesTool.name]: listFilesTool,
 	[grepTool.name]: grepTool,
 	[findFileTool.name]: findFileTool,
-	[editFileTool.name]: editFileTool
+	[editFileTool.name]: editFileTool,
+	[inspectCommandTool.name]: inspectCommandTool
 };
 function isToolName(name) {
 	return name in toolRegistry;
@@ -3468,6 +4293,15 @@ function summarizeToolArgs(call) {
 	};
 }
 function summarizeToolResult(result) {
+	if (result.tool === "inspect_command") return {
+		cwd: result.cwd,
+		exitCode: result.exitCode,
+		timedOut: result.timedOut,
+		truncated: result.truncated,
+		decision: result.decision,
+		stdoutLength: result.stdout.length,
+		stderrLength: result.stderr.length
+	};
 	if (result.tool !== "edit_file") return {};
 	return {
 		beforeHash: result.beforeHash,
@@ -3554,6 +4388,9 @@ function getChatSystemPrompt() {
 		"- 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 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.",
 		"- Keep edit_file old_text small but unique. Do not include line labels or grep prefixes in old_text; use exact file text only.",
@@ -3695,6 +4532,18 @@ function formatToolResultForPrompt(result) {
 		result.diff,
 		"```"
 	].join("\n");
+	if (result.tool === "inspect_command") return [
+		`Tool result from ${result.tool} via ${result.command}:`,
+		`cwd: ${result.cwd}`,
+		`exit_code: ${result.exitCode}`,
+		`timed_out: ${result.timedOut}`,
+		`truncated: ${result.truncated}`,
+		`decision: ${result.decision.reason}`,
+		warning ? warning.trimStart() : "",
+		"```",
+		result.content,
+		"```"
+	].filter(Boolean).join("\n");
 	return [
 		`Tool result from ${result.tool}${path}${command}:${warning}`,
 		"```",
@@ -3704,11 +4553,12 @@ function formatToolResultForPrompt(result) {
 }
 function formatToolCallMessage(call, result) {
 	switch (call.tool) {
-		case "read_file": return `Tool read_file: ${call.args.path}`;
-		case "list_files": return `Tool list_files: ${call.args.path}${call.args.recursive ? " (recursive)" : ""}`;
-		case "grep": return `Tool grep: ${call.args.pattern} in ${call.args.path ?? "."}`;
-		case "find_file": return `Tool find_file: ${call.args.query} in ${call.args.path}`;
-		case "edit_file": return `Tool edit_file: ${call.args.path}${formatEditFileChangeSummary(result)}`;
+		case "read_file": return `read_file: ${call.args.path}`;
+		case "list_files": return `list_files: ${call.args.path}${call.args.recursive ? " (recursive)" : ""}`;
+		case "grep": return `grep: ${call.args.pattern} in ${call.args.path ?? "."}`;
+		case "find_file": return `find_file: ${call.args.query} in ${call.args.path}`;
+		case "edit_file": return `edit_file: ${call.args.path}${formatEditFileChangeSummary(result)}`;
+		case "inspect_command": return `inspect_command: ${call.args.command}`;
 	}
 }
 function formatEditFileChangeSummary(result) {
@@ -3739,7 +4589,7 @@ function renderRuntimeEvent(event) {
 	switch (event.type) {
 		case "message": return [event.role === "assistant" ? agentMessage(event.text, event.meta) : systemMessage(event.text)];
 		case "tool_call": return [systemMessage(event.label)];
-		case "knowledge_status": return [systemMessage(`KB status: ${formatPathStatus$1(event.status.kbPath, event.status.kbExists, event.status.kbIsDirectory)} (${event.status.kbPathSource})`)];
+		case "knowledge_status": return [systemMessage(`KB status: ${formatKnowledgePathStatus$1(event.status)}${formatKbPathSource(event.status)}`)];
 		case "choice": return [modalMessage({
 			tone: event.tone,
 			title: event.title,
@@ -3749,6 +4599,9 @@ function renderRuntimeEvent(event) {
 		case "status": return [];
 	}
 }
+function formatKbPathSource(status) {
+	return status.kbPathSource === "env" ? " (custom)" : "";
+}
 //#endregion
 //#region src/tui/terminal.ts
 function enterAlternateScreen(terminal) {
@@ -4135,10 +4988,11 @@ kbCommand.command("status").description("show project knowledge base status").ac
 	const status = await ui.spinner("Checking knowledge base...", () => getKnowledgeStatus(context.workspaceRoot));
 	console.log(ui.heading("KB status"));
 	console.log(`${ui.label("workspace")}: ${status.workspaceRoot}`);
-	console.log(`${ui.label("knowledge folder")}: ${formatPathStatus(status.kbPath, status.kbExists, status.kbIsDirectory)} ${ui.label(`(${status.kbPathSource})`)}`);
+	console.log(`${ui.label("knowledge folder")}: ${formatKnowledgePathStatus(status)} ${ui.label(`(${status.kbPathSource})`)}`);
 	console.log(`${ui.label("local cache folder")}: ${formatPathStatus(status.cachePath, status.cacheExists, status.cacheIsDirectory)} ${ui.label(`(${status.cachePathSource})`)}`);
 	if (!status.kbExists) console.log(`${ui.label("state")}: ${ui.warn("no knowledge base found yet")}`);
 	else if (!status.kbIsDirectory) console.log(`${ui.label("state")}: ${ui.error("knowledge base path is not a folder")}`);
+	else if (status.kbContentState !== "ready") console.log(`${ui.label("state")}: ${ui.label("knowledge base folder is empty")}`);
 	else console.log(`${ui.label("state")}: ${ui.ok("knowledge base found")}`);
 });
 await program.parseAsync();
@@ -4190,6 +5044,12 @@ function formatPathStatus(path, exists, isDirectory) {
 	if (!isDirectory) return `${path} ${ui.error("[not a folder]")}`;
 	return `${path} ${ui.ok("[ok]")}`;
 }
+function formatKnowledgePathStatus(status) {
+	if (!status.kbExists) return `${status.kbPath} ${ui.warn("[missing]")}`;
+	if (!status.kbIsDirectory) return `${status.kbPath} ${ui.error("[not a folder]")}`;
+	if (status.kbContentState !== "ready") return `${status.kbPath} ${ui.label("[empty]")}`;
+	return `${status.kbPath} ${ui.ok("[ok]")}`;
+}
 //#endregion
 export {};