@oh-my-pi/pi-coding-agent 17.1.8 → 17.2.1

package/src/tools/read.ts

@@ -735,6 +735,8 @@ export interface ReadToolDetails {
 	method?: string;
 	notes?: string[];
 	meta?: OutputMeta;
+	/** Full on-disk byte size recorded before applying a file range. */
+	fileSize?: number;
 	/** Raw text + start line for user-visible TUI rendering, set when content is text-like.
 	 * Mirrors the same lines the model receives but without hashline/line-number prefixes,
 	 * so the TUI can render the file content with its own gutter without re-parsing the formatted text. */
@@ -2959,6 +2961,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			}
 		}
 
+		details.fileSize = fileSize;
 		this.#markMarkdownContentType(details, absolutePath);
 		if (suffixResolution) {
 			details.suffixResolution = suffixResolution;

package/src/tools/security-scan.ts

@@ -0,0 +1,287 @@
+import type { AgentTool, AgentToolResult, ToolTier } from "@oh-my-pi/pi-agent-core";
+import { type } from "arktype";
+import securityScanDescription from "../prompts/tools/security-scan.md" with { type: "text" };
+import { selectSecurityAccount } from "../security/auth";
+import {
+	CodexSecurityCloudClient,
+	type CodexSecurityCloudConfiguration,
+	type CodexSecurityCloudStats,
+	pullCodexSecurityCloudResults,
+} from "../security/cloud";
+import { createSecurityEvidenceId, type SecurityEvidence, type SecurityValidationStatus } from "../security/contracts";
+import type { SecurityOperationSnapshot } from "../security/coordinator";
+import { getSecurityCoordinator } from "../security/coordinator";
+import type { SecurityTargetRequest } from "../security/preflight";
+import { SecurityStore } from "../security/store";
+import type { ToolSession } from "./index";
+import { ToolError } from "./tool-errors";
+
+const securityScanSchema = type({
+	action:
+		"'preflight' | 'start' | 'status' | 'cancel' | 'validate' | 'cloud_scans' | 'cloud_start' | 'cloud_status' | 'cloud_pull'",
+	"plan_id?": "string",
+	"operation_id?": "string",
+	"target_kind?": "'repository' | 'scoped_path' | 'ref_diff' | 'working_tree'",
+	"include_paths?": "string[]",
+	"exclude_paths?": "string[]",
+	"base_revision?": "string",
+	"head_revision?": "string",
+	"knowledge_base_paths?": "string[]",
+	"output_root?": "string",
+	"archive_existing?": "boolean",
+	"credential_id?": "number.integer >= 1",
+	"scan_id?": "string",
+	"finding_id?": "string",
+	"validation_status?": "'unvalidated' | 'validated' | 'rejected' | 'partial' | 'error'",
+	"validation_summary?": "string",
+	"validation_evidence?": type({ label: "string > 0", explanation: "string" }).array(),
+	"cloud_configuration_id?": "string",
+	"repository_id?": "string",
+	"repository_url?": "string",
+	"environment_id?": "string",
+	"lookback_days?": "number.integer >= 1 | 'all'",
+});
+
+type SecurityScanParams = typeof securityScanSchema.infer;
+
+export interface SecurityScanToolDetails {
+	action: SecurityScanParams["action"];
+	plan?: { id: string; fingerprint: string };
+	operation?: SecurityOperationSnapshot;
+	cancelled?: boolean;
+	finding?: { id: string; validationStatus: SecurityValidationStatus };
+	cloudConfigurations?: CodexSecurityCloudConfiguration[];
+	cloudStats?: CodexSecurityCloudStats;
+	cloudScan?: { id: string; repositoryUrl: string };
+	importedScan?: { id: string; findingCount: number };
+}
+
+function targetFromParams(params: SecurityScanParams): SecurityTargetRequest {
+	const common = { includePaths: params.include_paths, excludePaths: params.exclude_paths };
+	switch (params.target_kind ?? "repository") {
+		case "scoped_path": {
+			if (!params.include_paths?.some(value => value.trim().length > 0)) {
+				throw new ToolError("scoped_path security scans require at least one include path");
+			}
+			return { kind: "scoped_path", includePaths: params.include_paths, excludePaths: params.exclude_paths };
+		}
+		case "working_tree":
+			return { kind: "working_tree", ...common };
+		case "ref_diff":
+			if (!params.base_revision || !params.head_revision) {
+				throw new ToolError("ref_diff preflight requires base_revision and head_revision");
+			}
+			return {
+				kind: "ref_diff",
+				baseRevision: params.base_revision,
+				headRevision: params.head_revision,
+				...common,
+			};
+		default:
+			return { kind: "repository", ...common };
+	}
+}
+
+function requireValue(value: string | undefined, label: string): string {
+	if (!value?.trim()) throw new ToolError(`${label} is required for this action`);
+	return value.trim();
+}
+
+function cloudClientForSession(session: ToolSession, credentialId?: number): CodexSecurityCloudClient {
+	if (!session.authStorage) throw new ToolError("Codex Security cloud requires the authentication registry");
+	const account = selectSecurityAccount(
+		session.authStorage,
+		"openai-codex",
+		credentialId,
+		session.getSessionId?.() ?? undefined,
+	);
+	return new CodexSecurityCloudClient({ authStorage: session.authStorage, account });
+}
+
+function textResult(text: string, details: SecurityScanToolDetails): AgentToolResult<SecurityScanToolDetails> {
+	return { content: [{ type: "text", text }], details };
+}
+
+export class SecurityScanTool implements AgentTool<typeof securityScanSchema, SecurityScanToolDetails> {
+	readonly name = "security_scan";
+	readonly approval: ToolTier = "exec";
+	readonly label = "Security Scan";
+	readonly loadMode = "discoverable";
+	readonly summary = "Run OMP-native scans and explicit Codex Security cloud operations";
+	readonly description = securityScanDescription.trim();
+	readonly parameters = securityScanSchema;
+	readonly strict = true;
+
+	constructor(readonly session: ToolSession) {}
+
+	async execute(
+		_toolCallId: string,
+		params: SecurityScanParams,
+		signal?: AbortSignal,
+	): Promise<AgentToolResult<SecurityScanToolDetails>> {
+		if (!this.session.settings.get("security.enabled")) {
+			throw new ToolError("Security is disabled. Enable security.enabled before using security_scan.");
+		}
+		const coordinatorForSession = () => {
+			if (!this.session.modelRegistry || !this.session.authStorage) {
+				throw new ToolError("Security scan requires the session model and authentication registries");
+			}
+			return getSecurityCoordinator({
+				cwd: this.session.cwd,
+				settings: this.session.settings,
+				authStorage: this.session.authStorage,
+				modelRegistry: this.session.modelRegistry,
+				activeModel: this.session.getActiveModel?.(),
+				sessionId: this.session.getSessionId?.() ?? undefined,
+				agentId: this.session.getAgentId?.() ?? undefined,
+				asyncJobManager: this.session.asyncJobManager,
+			});
+		};
+		switch (params.action) {
+			case "preflight": {
+				const model = this.session.getActiveModel?.();
+				const plan = await coordinatorForSession().preflight({
+					target: targetFromParams(params),
+					knowledgeBasePaths: params.knowledge_base_paths,
+					outputRoot: params.output_root,
+					archiveExisting: params.archive_existing,
+					credentialId: params.credential_id,
+					model,
+					signal,
+				});
+				return textResult(
+					[
+						`Security plan ${plan.id} is ready.`,
+						`Fingerprint: ${plan.fingerprint}.`,
+						`Start it with action=start and plan_id=${plan.id}.`,
+					].join(" "),
+					{ action: params.action, plan: { id: plan.id, fingerprint: plan.fingerprint } },
+				);
+			}
+			case "start": {
+				const operation = await coordinatorForSession().start({
+					planId: requireValue(params.plan_id, "plan_id"),
+				});
+				return textResult(`Security scan ${operation.scanId} started as ${operation.operationId}.`, {
+					action: params.action,
+					operation,
+				});
+			}
+			case "status": {
+				const operationId = requireValue(params.operation_id, "operation_id");
+				const operation = await coordinatorForSession().status(operationId);
+				if (!operation) throw new ToolError(`Unknown security operation: ${operationId}`);
+				return textResult(
+					`Security scan ${operation.scanId}: ${operation.phase}; ${operation.findingCount} finding(s).`,
+					{ action: params.action, operation },
+				);
+			}
+			case "cancel": {
+				const operationId = requireValue(params.operation_id, "operation_id");
+				const cancelled = await coordinatorForSession().cancel(operationId);
+				return textResult(
+					cancelled ? `Cancellation requested for ${operationId}.` : `No running operation ${operationId}.`,
+					{
+						action: params.action,
+						cancelled,
+						operation: (await coordinatorForSession().status(operationId)) ?? undefined,
+					},
+				);
+			}
+			case "cloud_scans": {
+				const configurations = await cloudClientForSession(
+					this.session,
+					params.credential_id,
+				).listAllConfigurations(signal);
+				return textResult(
+					configurations.length === 0
+						? "No Codex Security cloud scan configurations are available."
+						: configurations
+								.map(
+									item =>
+										`${item.id} ${item.currentStep ?? "unknown"} repo=${item.repositoryId} environment=${item.environmentId} ${item.repositoryUrl}`,
+								)
+								.join("\n"),
+					{ action: params.action, cloudConfigurations: configurations },
+				);
+			}
+			case "cloud_start": {
+				const configuration = await cloudClientForSession(this.session, params.credential_id).startScan({
+					repositoryId: requireValue(params.repository_id, "repository_id"),
+					repositoryUrl: requireValue(params.repository_url, "repository_url"),
+					environmentId: requireValue(params.environment_id, "environment_id"),
+					lookbackDays: params.lookback_days,
+					signal,
+				});
+				return textResult(
+					`Codex Security cloud scan ${configuration.id} started for ${configuration.repositoryUrl}. This consumes cloud scan allowance.`,
+					{
+						action: params.action,
+						cloudScan: { id: configuration.id, repositoryUrl: configuration.repositoryUrl },
+					},
+				);
+			}
+			case "cloud_status": {
+				const stats = await cloudClientForSession(this.session, params.credential_id).getStats(
+					requireValue(params.cloud_configuration_id, "cloud_configuration_id"),
+					signal,
+				);
+				return textResult(
+					`Codex Security cloud scan ${stats.configurationId}: ${stats.currentStep ?? "unknown"}; ${stats.finishedCommits} finished commit(s), ${stats.pendingCommits} pending.`,
+					{ action: params.action, cloudStats: stats },
+				);
+			}
+			case "cloud_pull": {
+				const store = await SecurityStore.openForCwd(this.session.cwd, { signal });
+				const bundle = await pullCodexSecurityCloudResults({
+					client: cloudClientForSession(this.session, params.credential_id),
+					configurationId: requireValue(params.cloud_configuration_id, "cloud_configuration_id"),
+					store,
+					signal,
+				});
+				return textResult(
+					`Imported ${bundle.findings.length} Codex Security cloud finding(s) as security scan ${bundle.scan.id}.`,
+					{
+						action: params.action,
+						importedScan: { id: bundle.scan.id, findingCount: bundle.findings.length },
+					},
+				);
+			}
+			case "validate": {
+				const scanId = requireValue(params.scan_id, "scan_id");
+				const findingId = requireValue(params.finding_id, "finding_id");
+				const status = params.validation_status;
+				if (!status) throw new ToolError("validation_status is required for this action");
+				const summary = requireValue(params.validation_summary, "validation_summary");
+				const store = await SecurityStore.openForCwd(this.session.cwd, { signal });
+				const finding = await store.getFinding(scanId, findingId);
+				if (!finding) throw new ToolError(`Unknown security finding: ${findingId}`);
+				const evidence: SecurityEvidence[] = (params.validation_evidence ?? []).map((item, index) => ({
+					id: createSecurityEvidenceId(
+						finding.fingerprint,
+						`validation:${item.label}`,
+						finding.evidence.length + index,
+					),
+					kind: "validation",
+					label: item.label,
+					explanation: item.explanation,
+				}));
+				const updated = await store.updateValidation(
+					scanId,
+					findingId,
+					{
+						status,
+						summary,
+						evidenceIds: evidence.map(item => item.id),
+						validatedAt: new Date().toISOString(),
+					},
+					evidence,
+				);
+				return textResult(`Finding ${updated.id} validation is now ${updated.validation.status}.`, {
+					action: params.action,
+					finding: { id: updated.id, validationStatus: updated.validation.status },
+				});
+			}
+		}
+	}
+}

package/src/tools/write.ts

@@ -1267,9 +1267,15 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 
 			// Try ACP bridge first for editor-visible filesystem paths. Internal
 			// artifacts such as local:// plans are owned by OMP, not the editor.
-			if (await routeWriteThroughBridge(this.session, path, absolutePath, cleanContent, signal)) {
-				const madeExecutable = await maybeMarkExecutableForShebang(absolutePath, cleanContent);
-				const header = maybeWriteSnapshotHeader(this.session, absolutePath, cleanContent);
+			const bridgeWrite = await routeWriteThroughBridge(this.session, path, absolutePath, cleanContent, signal);
+			if (bridgeWrite) {
+				// `write` always replaces the whole file, so (unlike hashline's
+				// hunk-scoped diff) there's no size cost to keying the header/
+				// executable-bit check on the verified post-write content —
+				// use it so a drifted write (e.g. client format-on-save) still
+				// hands back a tag that matches what's actually on disk.
+				const madeExecutable = await maybeMarkExecutableForShebang(absolutePath, bridgeWrite.text);
+				const header = maybeWriteSnapshotHeader(this.session, absolutePath, bridgeWrite.text);
 				const writeLine = `Successfully wrote ${cleanContent.length} bytes to ${displayPath}`;
 				let resultText = header ? `${header}\n${writeLine}` : writeLine;
 				if (stripped) {

package/src/tools/xdev.ts

@@ -35,6 +35,7 @@ import { parseStreamingJson } from "@oh-my-pi/pi-utils";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { XD_URL_PREFIX } from "../internal-urls/xd-protocol";
 import type { Theme } from "../modes/theme/theme";
+import { truncateHeadBytes } from "../session/streaming-output";
 import { renderDefaultToolExecution } from "./default-renderer";
 import type { Tool } from "./index";
 import { replaceTabs } from "./render-utils";
@@ -178,14 +179,34 @@ function toolSummary(inst: Tool): string {
 	return firstLine?.trim() ?? inst.label ?? inst.name;
 }
 
-function promptCatalogSummary(inst: Tool, maxLength?: number): string {
+/** C0/C1 controls and Unicode line/paragraph separators; summaries must remain one line. */
+const SUMMARY_CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]+/g;
+const SUMMARY_ELLIPSIS = "…";
+const SUMMARY_ELLIPSIS_BYTES = Buffer.byteLength(SUMMARY_ELLIPSIS, "utf-8");
+
+/**
+ * Bound a catalog summary for prompt rendering. External summaries are
+ * third-party metadata inlined verbatim, so control characters are stripped
+ * first, then the result is bounded in UTF-8 BYTES rather than characters (a
+ * character bound is not a byte bound for multi-byte scripts). The cut lands
+ * on a code point boundary, so the prompt never carries a partial code point.
+ */
+function sanitizeCatalogSummary(summary: string, maxBytes?: number): string {
+	const cleaned = summary.replace(SUMMARY_CONTROL_CHARS, " ").trim();
+	if (maxBytes === undefined || Buffer.byteLength(cleaned, "utf-8") <= maxBytes) return cleaned;
+	if (maxBytes <= 0) return "";
+	if (maxBytes < SUMMARY_ELLIPSIS_BYTES) return truncateHeadBytes(cleaned, maxBytes).text;
+	const body = truncateHeadBytes(cleaned, maxBytes - SUMMARY_ELLIPSIS_BYTES).text.trimEnd();
+	return `${body}${SUMMARY_ELLIPSIS}`;
+}
+
+function promptCatalogSummary(inst: Tool, maxBytes?: number): string {
 	const summary =
 		toolSummary(inst)
 			.split("\n")
 			.find(line => line.trim().length > 0)
 			?.trim() ?? inst.name;
-	if (maxLength === undefined || summary.length <= maxLength) return summary;
-	return `${summary.slice(0, maxLength).trimEnd()}…`;
+	return sanitizeCatalogSummary(summary, maxBytes) || inst.name;
 }
 
 /** Compile the `tools.xdevInlineDevices` allowlist once per render, dropping
@@ -257,15 +278,19 @@ export function listXdevTools(state: XdevState): Tool[] {
 	});
 }
 
-/** `{name, summary}` pairs for prompt templates and `/tools` display. */
-export function xdevEntries(state: XdevState): Array<{ name: string; summary: string }> {
-	return listXdevTools(state).map(tool => ({
-		name: tool.name,
-		summary: promptCatalogSummary(
-			tool,
-			state.builtInNames.has(tool.name) ? undefined : XDEV_EXTERNAL_DESCRIPTION_CAP,
-		),
-	}));
+/** `{name, summary, dynamic}` triples for prompt templates and `/tools` display. */
+export function xdevEntries(state: XdevState): Array<{ name: string; summary: string; dynamic: boolean }> {
+	return listXdevTools(state).map(tool => {
+		// Built-ins are first-party; anything else carries third-party metadata. One
+		// boolean drives both the description cap and the flag callers present, so
+		// the two can never disagree about which summaries are untrusted.
+		const dynamic = !state.builtInNames.has(tool.name);
+		return {
+			name: tool.name,
+			summary: promptCatalogSummary(tool, dynamic ? XDEV_EXTERNAL_DESCRIPTION_CAP : undefined),
+			dynamic,
+		};
+	});
 }
 
 /** `read xd://` listing with one device per line. */
@@ -313,8 +338,8 @@ export function xdevDocsAll(
 			[
 				"## Additional devices (docs on demand)",
 				...overflow.map(tool => {
-					const maxLength = state.builtInNames.has(tool.name) ? undefined : XDEV_EXTERNAL_DESCRIPTION_CAP;
-					return `- ${XD_URL_PREFIX}${tool.name} — ${promptCatalogSummary(tool, maxLength)}`;
+					const maxBytes = state.builtInNames.has(tool.name) ? undefined : XDEV_EXTERNAL_DESCRIPTION_CAP;
+					return `- ${XD_URL_PREFIX}${tool.name} — ${promptCatalogSummary(tool, maxBytes)}`;
 				}),
 				"",
 				`Read ${XD_URL_PREFIX}<tool> for full docs + JSON schema before first use.`,

package/src/utils/changelog.ts

@@ -1,6 +1,7 @@
 import * as path from "node:path";
 import { getLastChangelogVersionPath, isEnoent, logger } from "@oh-my-pi/pi-utils";
 import bundledChangelogPath from "../../CHANGELOG.md" with { type: "file" };
+import type { SettingValue } from "../config/settings";
 
 export interface ChangelogEntry {
 	major: number;
@@ -28,6 +29,101 @@ export interface StartupChangelogSelection {
 	persistCurrentVersion: boolean;
 	truncated: boolean;
 	selectedEntries: number;
+	totalUnseenEntries: number;
+	latestVersion: string | undefined;
+	changeCount: number;
+	categoryCounts: Record<string, number>;
+}
+
+const CHANGELOG_CATEGORY_ORDER = [
+	"Breaking Changes",
+	"Added",
+	"Changed",
+	"Deprecated",
+	"Removed",
+	"Fixed",
+	"Security",
+] as const;
+
+function emptyStartupSelection(persistCurrentVersion: boolean): StartupChangelogSelection {
+	return {
+		markdown: undefined,
+		persistCurrentVersion,
+		truncated: false,
+		selectedEntries: 0,
+		totalUnseenEntries: 0,
+		latestVersion: undefined,
+		changeCount: 0,
+		categoryCounts: {},
+	};
+}
+
+function summarizeChangelogEntries(entries: readonly ChangelogEntry[]): {
+	changeCount: number;
+	categoryCounts: Record<string, number>;
+} {
+	const categoryCounts: Record<string, number> = {};
+	let changeCount = 0;
+
+	for (const entry of entries) {
+		let category: string | undefined;
+		for (const line of entry.content.split("\n")) {
+			const heading = line.match(/^###\s+(.+?)\s*$/);
+			if (heading) {
+				category = heading[1];
+				continue;
+			}
+			if (!category || !/^-\s+\S/.test(line)) continue;
+			categoryCounts[category] = (categoryCounts[category] ?? 0) + 1;
+			changeCount++;
+		}
+	}
+
+	return { changeCount, categoryCounts };
+}
+
+function categoryLabel(category: string, count: number): string {
+	if (category === "Breaking Changes") {
+		return count === 1 ? "breaking change" : "breaking changes";
+	}
+	return category.toLowerCase();
+}
+
+/** Format the compact, deterministic startup update notice. */
+export function formatStartupChangelogSummary(selection: StartupChangelogSelection): string {
+	const latestVersion = selection.latestVersion;
+	if (!latestVersion || selection.selectedEntries === 0) {
+		return "Updated omp. Use /changelog for recent changes.";
+	}
+
+	const releaseCount = selection.selectedEntries;
+	const changeCount = selection.changeCount;
+	const releaseWord = releaseCount === 1 ? "release" : "releases";
+	const changeWord = changeCount === 1 ? "change" : "changes";
+	const firstLine =
+		releaseCount === 1
+			? `Updated to v${latestVersion} · ${changeCount} ${changeWord} in 1 release`
+			: `Updated to v${latestVersion} · ${changeCount} ${changeWord} across ${releaseCount} ${releaseWord}`;
+
+	const orderedCategories = [
+		...CHANGELOG_CATEGORY_ORDER.filter(category => selection.categoryCounts[category]),
+		...Object.keys(selection.categoryCounts)
+			.filter(category => !(CHANGELOG_CATEGORY_ORDER as readonly string[]).includes(category))
+			.sort(),
+	];
+	const breakdown = orderedCategories
+		.map(
+			category =>
+				`${selection.categoryCounts[category]} ${categoryLabel(category, selection.categoryCounts[category])}`,
+		)
+		.join(" · ");
+	const omittedReleases = selection.totalUnseenEntries - selection.selectedEntries;
+	const detailHint =
+		omittedReleases > 0
+			? `+${omittedReleases} earlier ${omittedReleases === 1 ? "release" : "releases"} · Use /changelog full for history.`
+			: "Use /changelog for details.";
+
+	return breakdown ? `${firstLine}\n${breakdown} · ${detailHint}` : `${firstLine}\n${detailHint}`;
 }
 
 /**
@@ -177,16 +273,17 @@ export function selectStartupChangelog(
 ): StartupChangelogSelection {
 	const parsedLastVersion = parseChangelogVersion(lastVersion);
 	if (!parsedLastVersion) {
-		return { markdown: undefined, persistCurrentVersion: true, truncated: false, selectedEntries: 0 };
+		return emptyStartupSelection(true);
 	}
 	const markerVersion = lastVersion ?? "";
 	if (markerVersion === currentVersion) {
-		return { markdown: undefined, persistCurrentVersion: false, truncated: false, selectedEntries: 0 };
+		return emptyStartupSelection(false);
 	}
 
-	const newEntries = getNewEntries(entries, markerVersion).slice(0, RECENT_CHANGELOG_ENTRY_LIMIT);
+	const allNewEntries = getNewEntries(entries, markerVersion);
+	const newEntries = allNewEntries.slice(0, RECENT_CHANGELOG_ENTRY_LIMIT);
 	if (newEntries.length === 0) {
-		return { markdown: undefined, persistCurrentVersion: false, truncated: false, selectedEntries: 0 };
+		return emptyStartupSelection(false);
 	}
 
 	const rendered = renderChangelogEntries(newEntries, {
@@ -194,14 +291,57 @@ export function selectStartupChangelog(
 		truncationHint: STARTUP_CHANGELOG_FULL_HINT,
 		oldestFirst: false,
 	});
+	const summary = summarizeChangelogEntries(newEntries);
+	const latestEntry = newEntries[0];
 	return {
 		markdown: rendered.markdown,
 		persistCurrentVersion: true,
 		truncated: rendered.truncated,
 		selectedEntries: newEntries.length,
+		totalUnseenEntries: allNewEntries.length,
+		latestVersion: latestEntry ? `${latestEntry.major}.${latestEntry.minor}.${latestEntry.patch}` : undefined,
+		...summary,
 	};
 }
 
+/**
+ * Resolve and persist the automatic startup changelog decision.
+ *
+ * Hidden mode advances the marker only for an upgrade, so downgrades do not
+ * erase knowledge of a newer version the user has already seen.
+ */
+export async function resolveStartupChangelogForDisplay(options: {
+	mode: SettingValue<"startup.changelogMode">;
+	currentVersion: string;
+	changelogPath?: string;
+	agentDir?: string;
+}): Promise<StartupChangelogSelection | undefined> {
+	const lastVersion = await readLastChangelogVersion(options.agentDir);
+	const parsedLastVersion = parseChangelogVersion(lastVersion);
+	if (!parsedLastVersion) {
+		await writeLastChangelogVersion(options.currentVersion, options.agentDir);
+		return undefined;
+	}
+	if (lastVersion === options.currentVersion) {
+		// Steady state: skip the changelog file read and parse.
+		return undefined;
+	}
+	if (options.mode === "hidden") {
+		const currentVersion = parseChangelogVersion(options.currentVersion);
+		if (currentVersion && compareVersions(currentVersion, parsedLastVersion) > 0) {
+			await writeLastChangelogVersion(options.currentVersion, options.agentDir);
+		}
+		return undefined;
+	}
+
+	const entries = await parseChangelog(options.changelogPath);
+	const startupChangelog = selectStartupChangelog(entries, lastVersion, options.currentVersion);
+	if (startupChangelog.persistCurrentVersion) {
+		await writeLastChangelogVersion(options.currentVersion, options.agentDir);
+	}
+	return startupChangelog.markdown ? startupChangelog : undefined;
+}
+
 // Re-export getChangelogPath from paths.ts for convenience
 export { getChangelogPath } from "../config";