@herbertgao/pi-extensions 2026.9.19 → 2026.10.0

package/node_modules/@herbertgao/pi-cc-extensions/extensions/feature/reference/index.ts

@@ -14,6 +14,7 @@ import {
 import {
 	SESSION_REFERENCE_CUSTOM_TYPE,
 	SESSION_REFERENCE_PREFIX,
+	assignReferenceTokens,
 	buildReferenceContentFromSections,
 	extractSessionReferenceIds,
 	formatReferenceSession,
@@ -26,8 +27,6 @@ const MAX_SESSION_SUGGESTIONS = 3;
 const MAX_FILE_SUGGESTIONS = 7;
 const MAX_REFERENCED_SESSIONS = 5;
 const MENTION_PATTERN = /(?:^|[\t ])@([^\s@]*)$/;
-const SUBAGENT_MANAGER_KEY = Symbol.for("pi-subagents:manager");
-
 // ── In-process subagent record tracker ──────────────────────────────
 // pi-subagents does not expose a global manager; we track records
 // ourselves by listening to the events it emits.
@@ -53,17 +52,6 @@ type SessionReference = {
 	messages?: unknown[];
 };
 
-type SubagentRecord = {
-	id: string;
-	description?: string;
-	startedAt?: number;
-	completedAt?: number;
-};
-
-type SubagentManager = {
-	getRecord(id: string): SubagentRecord | undefined;
-};
-
 // Local subagent record tracking (pi-subagents does not expose a global manager).
 const liveSubagentRecords = new Map<string, SubagentLiveRecord>();
 /** Cap retained completed/live records so long-lived pi processes cannot grow unbounded. */
@@ -109,7 +97,7 @@ function trackSubagentFromEvent(data: unknown): void {
 	// Started event — create new record
 	const agent = typeof event.agent === "string" ? event.agent : "";
 	const cwd = typeof event.cwd === "string" ? event.cwd : "";
-	const startedAt = typeof event.startedAt === "number" ? (event.startedAt as number) : Date.now();
+	const startedAt = typeof event.startedAt === "number" ? event.startedAt : Date.now();
 	liveSubagentRecords.set(runId, {
 		runId,
 		sessionId,
@@ -120,26 +108,6 @@ function trackSubagentFromEvent(data: unknown): void {
 	pruneLiveSubagentRecords();
 }
 
-function getSubagentManager(): SubagentManager | undefined {
-	// Try the global manager first (future-proof), fall back to local records.
-	const manager = (globalThis as any)[SUBAGENT_MANAGER_KEY] as SubagentManager | undefined;
-	if (manager && typeof manager.getRecord === "function") return manager;
-	// If no global manager, use our local tracking.
-	if (liveSubagentRecords.size === 0) return undefined;
-	return {
-		getRecord(id: string): SubagentRecord | undefined {
-			const record = liveSubagentRecords.get(id);
-			if (!record) return undefined;
-			return {
-				id: record.runId,
-				description: record.agent || undefined,
-				startedAt: record.startedAt,
-				completedAt: record.completedAt,
-			};
-		},
-	};
-}
-
 function extractMentionQuery(textBeforeCursor: string): string | undefined {
 	return textBeforeCursor.match(MENTION_PATTERN)?.[1];
 }
@@ -156,7 +124,7 @@ function formatDate(date: Date): string {
 const sessionSearchTextCache = new WeakMap<SessionReference, string>();
 const sessionItemCache = new WeakMap<
 	SessionReference,
-	{ cwd: string; named?: AutocompleteItem; stable?: AutocompleteItem }
+	{ cwd: string; token: string; item: AutocompleteItem }
 >();
 
 function sessionSearchText(reference: SessionReference): string {
@@ -171,30 +139,24 @@ function sessionSearchText(reference: SessionReference): string {
 function sessionItem(
 	reference: SessionReference,
 	currentCwd: string,
-	useStableId: boolean,
+	token: string,
 ): AutocompleteItem {
-	let cached = sessionItemCache.get(reference);
-	const variant = useStableId ? "stable" : "named";
-	if (cached?.cwd === currentCwd && cached[variant]) return cached[variant];
+	const cached = sessionItemCache.get(reference);
+	if (cached?.cwd === currentCwd && cached.token === token) return cached.item;
 
 	const session = reference.info;
 	const workspace = samePath(session.cwd, currentCwd)
 		? "current workspace"
 		: session.cwd || "unknown workspace";
-	const label = reference.kind === "subagent" ? "[SubAgent]" : "[Session]";
-	// 唯一名称保持短格式；同名或无名称时使用稳定 ID，避免引用歧义。
-	const sessionName = session.name?.trim();
-	const referenceId = useStableId
-		? reference.referenceIds[0]
-		: (sessionName ?? reference.referenceIds[0]);
+	const kindLabel = reference.kind === "subagent" ? "[SubAgent]" : "[Session]";
+	// 消歧后的 token 会带上日期；回落到 ID 时下拉仍显示可读标题。
+	const title = token === (reference.referenceIds[0] ?? session.id) ? sessionTitle(session) : token;
 	const item: AutocompleteItem = {
-		value: `${SESSION_REFERENCE_PREFIX}[${referenceId}]`,
-		label: `${label} ${sessionTitle(session)}`,
+		value: `${SESSION_REFERENCE_PREFIX}[${token}]`,
+		label: `${kindLabel} ${title}`,
 		description: `${workspace} · ${session.messageCount} messages · ${formatDate(session.modified)}`,
 	};
-	if (cached?.cwd !== currentCwd) cached = { cwd: currentCwd };
-	cached[variant] = item;
-	sessionItemCache.set(reference, cached);
+	sessionItemCache.set(reference, { cwd: currentCwd, token, item });
 	return item;
 }
 
@@ -230,11 +192,7 @@ function filterSessions(
 	if (query.startsWith("session:")) return [];
 
 	const ordered = orderSessionReferences(references, currentCwd);
-	const nameCounts = new Map<string, number>();
-	for (const reference of ordered) {
-		const name = reference.info.name?.trim();
-		if (name) nameCounts.set(name, (nameCounts.get(name) ?? 0) + 1);
-	}
+	const tokens = assignReferenceTokens(ordered);
 	const trimmed = query.trim();
 	// 模糊匹配只接受有 session name 的会话；subagent 按 agent name 匹配。
 	const searchable = ordered.filter(
@@ -244,10 +202,11 @@ function filterSessions(
 	const matches = trimmed
 		? fuzzyFilter(searchable, trimmed, sessionSearchText)
 		: ordered.slice(0, MAX_SESSION_SUGGESTIONS);
-	return matches.slice(0, MAX_SESSION_SUGGESTIONS).map((reference) => {
-		const name = reference.info.name?.trim();
-		return sessionItem(reference, currentCwd, Boolean(name && (nameCounts.get(name) ?? 0) > 1));
-	});
+	return matches
+		.slice(0, MAX_SESSION_SUGGESTIONS)
+		.map((reference) =>
+			sessionItem(reference, currentCwd, tokens.get(reference) ?? reference.info.id),
+		);
 }
 
 function isPathLikeQuery(query: string): boolean {
@@ -279,31 +238,20 @@ function liveSubagentReferences(
 	agentIds: Set<string>,
 	currentSessionId: string,
 ): SessionReference[] {
-	const manager = getSubagentManager();
-	if (!manager) return [];
-
 	const references: SessionReference[] = [];
 	for (const agentId of agentIds) {
-		const record = manager.getRecord(agentId);
-		if (!record) continue;
-
-		// Try the global manager's live session first (future-proof).
-		const liveRecord = liveSubagentRecords.get(agentId);
-		const sessionId = liveRecord?.sessionId ?? record.id;
-		if (!sessionId || sessionId === currentSessionId) continue;
-
-		const name = record.description?.trim() || liveRecord?.agent || undefined;
-		const modifiedAt = record.completedAt ?? record.startedAt ?? Date.now();
+		const record = liveSubagentRecords.get(agentId);
+		if (!record || record.sessionId === currentSessionId) continue;
 		references.push({
 			kind: "subagent",
-			referenceIds: [sessionId, agentId],
+			referenceIds: [record.sessionId, agentId],
 			info: {
-				id: sessionId,
-				name,
-				cwd: liveRecord?.cwd ?? "",
+				id: record.sessionId,
+				name: record.agent || undefined,
+				cwd: record.cwd,
 				firstMessage: "",
 				messageCount: 0,
-				modified: new Date(modifiedAt),
+				modified: new Date(record.completedAt ?? record.startedAt),
 			},
 		});
 	}
@@ -347,14 +295,14 @@ export function createAutocompleteProvider(
 			const currentLine = lines[cursorLine] ?? "";
 			const query = extractMentionQuery(currentLine.slice(0, cursorCol));
 			if (query === undefined) {
-				const suggestions = await current.getSuggestions(lines, cursorLine, cursorCol, options);
-				return options.signal.aborted || !isCurrent() ? null : suggestions;
+				return current.getSuggestions(lines, cursorLine, cursorCol, options);
 			}
 
 			const [baseSuggestions, references] = await Promise.all([
 				current.getSuggestions(lines, cursorLine, cursorCol, options),
 				getReferences(),
 			]);
+			// 会话已被替换时，旧会话的补全结果不能再泄漏到新会话。
 			if (options.signal.aborted || !isCurrent()) return null;
 
 			const sessionItems = filterSessions(references, query, currentCwd);
@@ -415,10 +363,13 @@ export default function sessionReferenceExtension(pi: ExtensionAPI): void {
 
 	pi.on("session_start", (_event, ctx) => {
 		const generation = ++sessionGeneration;
+		// 会话替换/reload 会让 ctx 的 getter 抛 stale 错误，await 之后不能再读；
+		// 这里在同步阶段一次性取出纯值。
+		const currentCwd = ctx.cwd;
+		const ui = ctx.ui;
 		subagentIds.clear();
 		clearLiveSubagentRecords();
 		let loadErrorShown = false;
-		const currentCwd = ctx.cwd;
 		const currentSessionId = ctx.sessionManager.getSessionId();
 		const currentSessionFile = ctx.sessionManager.getSessionFile();
 		let sessionsPromise: Promise<SessionInfo[]> | undefined;
@@ -435,7 +386,7 @@ export default function sessionReferenceExtension(pi: ExtensionAPI): void {
 					if (!loadErrorShown && generation === sessionGeneration) {
 						loadErrorShown = true;
 						const reason = error instanceof Error ? error.message : String(error);
-						ctx.ui.notify(`session-reference: failed to load sessions: ${reason}`, "error");
+						ui.notify(`session-reference: failed to load sessions: ${reason}`, "error");
 					}
 					return [];
 				});
@@ -448,7 +399,7 @@ export default function sessionReferenceExtension(pi: ExtensionAPI): void {
 			| undefined;
 		const getReferences = async (): Promise<SessionReference[]> => {
 			const sessions = await getSessions();
-			// Session replacement can invalidate this closure while listAll() is pending.
+			// 会话替换/reload 后丢弃旧 generation 的结果，避免对失效状态继续工作。
 			if (generation !== sessionGeneration) return [];
 			const subagentKey = [...subagentIds].join("\0");
 			if (
@@ -467,14 +418,15 @@ export default function sessionReferenceExtension(pi: ExtensionAPI): void {
 		};
 
 		getAvailableReferences = getReferences;
-		const isTui = ctx.mode === "tui";
-		if (isTui) {
-			void getReferences();
+		if (ctx.mode === "tui") {
+			// 预取是 detached 的，必须兜住 rejection，否则 stale 错误会变成
+			// unhandled rejection 直接终止 Pi。
+			void getReferences().catch(() => {});
 			// Register after other session_start handlers. pi-fff claims every @
 			// prefix, so a provider installed before it would never see session mentions.
 			setTimeout(() => {
 				if (generation !== sessionGeneration) return;
-				ctx.ui.addAutocompleteProvider((current) =>
+				ui.addAutocompleteProvider((current) =>
 					createAutocompleteProvider(
 						current,
 						getReferences,
@@ -492,38 +444,33 @@ export default function sessionReferenceExtension(pi: ExtensionAPI): void {
 
 		const generation = sessionGeneration;
 		const currentSessionId = ctx.sessionManager.getSessionId();
-		const references = await (getAvailableReferences?.() ??
-			SessionManager.listAll()
-				.then((sessions) =>
+		let references: SessionReference[];
+		try {
+			references = await (getAvailableReferences?.() ??
+				SessionManager.listAll().then((sessions) =>
 					mergeReferences(
 						sessions.filter((session) => session.id !== currentSessionId),
 						liveSubagentReferences(subagentIds, currentSessionId),
 					),
-				)
-				.catch((error: unknown) => {
-					if (generation !== sessionGeneration) return [];
-					const reason = error instanceof Error ? error.message : String(error);
-					ctx.ui.notify(`session-reference: failed to load sessions: ${reason}`, "error");
-					return [];
-				}));
+				));
+		} catch (error) {
+			if (generation !== sessionGeneration) return;
+			throw error;
+		}
+		// await 期间会话被替换/关闭：ctx 已失效，丢弃结果。
 		if (generation !== sessionGeneration) return;
 		const referencesById = new Map<string, SessionReference>();
-		const referencesByName = new Map<string, SessionReference>();
-		const ambiguousNames = new Set<string>();
+		const referencesByToken = new Map<string, SessionReference>();
 		for (const reference of references) {
 			for (const id of reference.referenceIds) referencesById.set(id, reference);
-			const name = reference.info.name?.trim();
-			if (!name || ambiguousNames.has(name)) continue;
-			if (referencesByName.has(name)) {
-				referencesByName.delete(name);
-				ambiguousNames.add(name);
-			} else {
-				referencesByName.set(name, reference);
-			}
+		}
+		// 同位重名的会话用带日期的 token 区分，解析端与补全端用同一套分配。
+		for (const [reference, token] of assignReferenceTokens(references)) {
+			referencesByToken.set(token, reference);
 		}
 		const seenReferences = new Set<SessionReference>();
 		const matchingReferences = referenceIds
-			.map((id) => referencesById.get(id) ?? referencesByName.get(id))
+			.map((id) => referencesById.get(id) ?? referencesByToken.get(id))
 			.filter((reference): reference is SessionReference => {
 				if (!reference || reference.info.id === currentSessionId || seenReferences.has(reference))
 					return false;
@@ -585,7 +532,8 @@ export default function sessionReferenceExtension(pi: ExtensionAPI): void {
 	});
 
 	pi.on("session_before_switch", () => {
-		// This event can cancel; preserve current-session state until shutdown.
+		subagentIds.clear();
+		clearLiveSubagentRecords();
 	});
 
 	pi.on("session_shutdown", () => {

package/node_modules/@herbertgao/pi-cc-extensions/extensions/feature/reference/session.ts

@@ -1,8 +1,10 @@
+import { truncateToWidth } from "@earendil-works/pi-tui";
+import { stripTerminalSequences } from "../../utils/ansi-text.ts";
+
 export const SESSION_REFERENCE_CUSTOM_TYPE = "session-reference";
 export const SESSION_REFERENCE_PREFIX = "@session:";
 
-const SESSION_REFERENCE_PATTERN =
-	/(?:^|\s)@session:(?:\[([^\]]+)\]|([A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?))(?![\w.\]-])/g;
+const SESSION_REFERENCE_PATTERN = /(?:^|\s)@session:\[([^\]]+)](?![\w-])/g;
 const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/g;
 
 export interface ReferenceSessionInfo {
@@ -31,13 +33,12 @@ export const DEFAULT_REFERENCE_LIMITS: ReferenceLimits = {
 	maxTotalBytes: 48_000,
 };
 
-/** 提取 @session:[name]（组 1）或旧格式 @session:id（组 2），返回 name 或 id。 */
 export function extractSessionReferenceIds(text: string): string[] {
 	const ids: string[] = [];
 	const seen = new Set<string>();
 
 	for (const match of text.matchAll(SESSION_REFERENCE_PATTERN)) {
-		const id = (match[1] ?? match[2])?.trim();
+		const id = match[1]?.trim();
 		if (id && !seen.has(id)) {
 			seen.add(id);
 			ids.push(id);
@@ -47,13 +48,104 @@ export function extractSessionReferenceIds(text: string): string[] {
 	return ids;
 }
 
+const EMPTY_SESSION_TITLE = "(no messages)";
+
 export function sessionTitle(info: ReferenceSessionInfo, maxLength = 80): string {
-	const source = info.name?.trim() || info.firstMessage || "(no messages)";
+	const source = info.name?.trim() || info.firstMessage || EMPTY_SESSION_TITLE;
 	const normalized = source.replace(CONTROL_CHARACTERS, " ").replace(/\s+/g, " ").trim();
 	if (normalized.length <= maxLength) return normalized;
 	return `${normalized.slice(0, Math.max(1, maxLength - 1)).trimEnd()}…`;
 }
 
+/**
+ * 编辑器里的 `@session:[…]` 是行内文本，token 按显示宽度收口，
+ * 不让首条消息整段挤进输入行。同名会话靠后缀消歧，不受它影响。
+ */
+export const REFERENCE_TOKEN_MAX_WIDTH = 32;
+
+/** Editor `@session:[…]` text: the readable title, never a placeholder or brackets. */
+export function sessionReferenceLabel(
+	info: ReferenceSessionInfo,
+	maxWidth = REFERENCE_TOKEN_MAX_WIDTH,
+): string {
+	const title = sessionTitle(info).replace(/[[\]]/g, "").trim();
+	if (!title || title === EMPTY_SESSION_TITLE) return "";
+	// truncateToWidth 会在省略号前后补 ANSI reset，token 是明文，去掉。
+	return stripTerminalSequences(truncateToWidth(title, maxWidth, "…")).trim();
+}
+
+export interface ReferenceTokenSource {
+	referenceIds: string[];
+	info: ReferenceSessionInfo;
+}
+
+/** UTC keeps the disambiguator identical across timezones (same-day drift is harmless). */
+function referenceTokenDate(date: Date): string {
+	const month = String(date.getUTCMonth() + 1).padStart(2, "0");
+	const day = String(date.getUTCDate()).padStart(2, "0");
+	return `${month}-${day}`;
+}
+
+function referenceTokenTime(date: Date): string {
+	const hours = String(date.getUTCHours()).padStart(2, "0");
+	const minutes = String(date.getUTCMinutes()).padStart(2, "0");
+	return `${hours}:${minutes}`;
+}
+
+/** Title first; date then time widen the disambiguation before the ID fallback. */
+function referenceTokenCandidates(reference: ReferenceTokenSource): string[] {
+	const title = sessionReferenceLabel(reference.info);
+	const stableId = reference.referenceIds[0] ?? reference.info.id;
+	if (!title) return [stableId];
+	const date = referenceTokenDate(reference.info.modified);
+	return [
+		title,
+		`${title} ${date}`,
+		`${title} ${date} ${referenceTokenTime(reference.info.modified)}`,
+		stableId,
+	];
+}
+
+/**
+ * Assign each reference a unique editor token. Same-named sessions keep a readable
+ * title plus a date/time suffix; the stable ID is only the last resort.
+ */
+export function assignReferenceTokens<T extends ReferenceTokenSource>(
+	references: T[],
+): Map<T, string> {
+	const candidates = new Map<T, string[]>();
+	let levels = 0;
+	for (const reference of references) {
+		const options = referenceTokenCandidates(reference);
+		levels = Math.max(levels, options.length);
+		candidates.set(reference, options);
+	}
+
+	const tokens = new Map<T, string>();
+	const taken = new Set<string>();
+	for (let level = 0; level < levels && tokens.size < references.length; level++) {
+		const counts = new Map<string, number>();
+		for (const [reference, options] of candidates) {
+			const candidate = tokens.has(reference) ? undefined : options[level];
+			if (candidate) counts.set(candidate, (counts.get(candidate) ?? 0) + 1);
+		}
+		for (const [reference, options] of candidates) {
+			if (tokens.has(reference)) continue;
+			const candidate = options[level];
+			if (candidate && counts.get(candidate) === 1 && !taken.has(candidate)) {
+				tokens.set(reference, candidate);
+				taken.add(candidate);
+			}
+		}
+	}
+	for (const reference of references) {
+		if (!tokens.has(reference)) {
+			tokens.set(reference, reference.referenceIds[0] ?? reference.info.id);
+		}
+	}
+	return tokens;
+}
+
 function byteLength(text: string): number {
 	return Buffer.byteLength(text, "utf8");
 }
@@ -250,13 +342,3 @@ export function buildReferenceContentFromSections(
 	].join("\n");
 	return truncateUtf8([header, ...sections].join("\n\n"), maxTotalBytes);
 }
-
-export function buildReferenceContent(
-	sources: ReferenceSource[],
-	limits: ReferenceLimits = DEFAULT_REFERENCE_LIMITS,
-): string {
-	return buildReferenceContentFromSections(
-		sources.map((source) => formatReferenceSession(source, limits)),
-		limits.maxTotalBytes,
-	);
-}

package/node_modules/@herbertgao/pi-cc-extensions/extensions/feature/reference/subagent.ts

@@ -18,13 +18,16 @@ type AgentInfo = {
 	filePath: string;
 };
 
+export const SUBAGENT_DELEGATION_CUSTOM_TYPE = "subagent-delegation";
+export const SUBAGENT_REFERENCE_PREFIX = "@subagent:";
+
 const MAX_SUGGESTIONS = 2;
-// Match `@name` but NOT `@session:` (reserved by session-reference extension).
-const AGENT_NAME_PATTERN = /(?:^|[\t ])@((?:[^\s:@][^\s:]*)?)$/;
+const MENTION_PATTERN = /(?:^|[\t ])@([^\s@]*)$/;
+const SUBAGENT_REFERENCE_PATTERN = /(?:^|\s)@subagent:\[([^\]]+)](?![\w-])/g;
 
 function getAgentDir(): string {
-	const root = process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
-	return join(root, "agents");
+	const override = process.env.PI_CODING_AGENT_DIR;
+	return join(override ? override : join(homedir(), ".pi", "agent"), "agents");
 }
 
 function parseFrontmatter(content: string): Record<string, string> {
@@ -41,34 +44,60 @@ function parseFrontmatter(content: string): Record<string, string> {
 function loadAgents(): AgentInfo[] {
 	const dir = getAgentDir();
 	if (!existsSync(dir)) return [];
-	let files: string[];
-	try {
-		files = readdirSync(dir);
-	} catch {
-		return [];
-	}
 
-	const agents: AgentInfo[] = [];
-	for (const file of files) {
-		if (!file.endsWith(".md")) continue;
-		try {
+	return readdirSync(dir)
+		.filter((f) => f.endsWith(".md"))
+		.flatMap((file) => {
 			const filePath = join(dir, file);
-			const content = readFileSync(filePath, "utf-8");
+			let content: string;
+			try {
+				content = readFileSync(filePath, "utf-8");
+			} catch {
+				return []; // 目录或不可读条目直接跳过
+			}
 			const fm = parseFrontmatter(content);
 			const name = file.replace(/\.md$/, "");
-			agents.push({
-				name,
-				displayName: fm.display_name || name,
-				description: fm.description || "",
-				model: fm.model,
-				thinking: fm.thinking,
-				filePath,
-			});
-		} catch {
-			// One unreadable agent file must not break autocomplete or prompt submission.
+			return [
+				{
+					name,
+					displayName: fm.display_name || name,
+					description: fm.description || "",
+					model: fm.model,
+					thinking: fm.thinking,
+					filePath,
+				},
+			];
+		});
+}
+
+function extractMentionQuery(textBeforeCursor: string): string | undefined {
+	return textBeforeCursor.match(MENTION_PATTERN)?.[1];
+}
+
+/** Filter text for agent names, or null when this provider should not claim the @ query. */
+function agentSearchQuery(raw: string): string | null {
+	if (raw.startsWith("session:")) return null;
+	if (raw === "subagent") return "";
+	const prefixed = raw.match(/^subagent:\[?([^\]]*)$/);
+	if (prefixed) return prefixed[1] ?? "";
+	return raw;
+}
+
+export function extractSubagentReferenceNames(text: string): string[] {
+	const names: string[] = [];
+	const seen = new Set<string>();
+	for (const match of text.matchAll(SUBAGENT_REFERENCE_PATTERN)) {
+		const name = match[1]?.trim();
+		if (name && !seen.has(name)) {
+			seen.add(name);
+			names.push(name);
 		}
 	}
-	return agents;
+	return names;
+}
+
+export function subagentReferenceValue(name: string): string {
+	return `${SUBAGENT_REFERENCE_PREFIX}[${name}]`;
 }
 
 export function createAgentAutocompleteProvider(
@@ -85,13 +114,16 @@ export function createAgentAutocompleteProvider(
 		): Promise<AutocompleteSuggestions | null> {
 			const currentLine = lines[cursorLine] ?? "";
 			const textBeforeCursor = currentLine.slice(0, cursorCol);
-			const match = textBeforeCursor.match(AGENT_NAME_PATTERN);
+			const rawQuery = extractMentionQuery(textBeforeCursor);
+			if (rawQuery === undefined) {
+				return current.getSuggestions(lines, cursorLine, cursorCol, options);
+			}
 
-			if (!match) {
+			const search = agentSearchQuery(rawQuery);
+			if (search === null) {
 				return current.getSuggestions(lines, cursorLine, cursorCol, options);
 			}
 
-			const query = match[1]!;
 			const agents = getAgents();
 
 			if (options.signal.aborted || agents.length === 0) {
@@ -100,17 +132,20 @@ export function createAgentAutocompleteProvider(
 
 			const [baseSuggestions, matches] = await Promise.all([
 				current.getSuggestions(lines, cursorLine, cursorCol, options),
-				Promise.resolve(query.trim() ? fuzzyFilter(agents, query, (a) => a.name) : agents),
+				Promise.resolve(search.trim() ? fuzzyFilter(agents, search, (a) => a.name) : agents),
 			]);
 			if (options.signal.aborted) return null;
 
 			const agentItems: AutocompleteItem[] = matches.slice(0, MAX_SUGGESTIONS).map((agent) => ({
-				value: `@${agent.name}`,
+				value: subagentReferenceValue(agent.name),
 				label: `[SubAgent] ${agent.displayName}`,
 				description: `${agent.model ?? "?"} · ${agent.thinking ?? "?"}`,
 			}));
-			const hasCompatibleBaseSuggestions = baseSuggestions?.prefix === `@${query}`;
-			const agentValues = new Set(agents.map((agent) => `@${agent.name}`));
+			const prefix = `@${rawQuery}`;
+			const hasCompatibleBaseSuggestions = baseSuggestions?.prefix === prefix;
+			const agentValues = new Set(
+				agents.flatMap((agent) => [`@${agent.name}`, subagentReferenceValue(agent.name)]),
+			);
 			const baseItems = hasCompatibleBaseSuggestions
 				? baseSuggestions.items.filter((item) => !agentValues.has(item.value))
 				: [];
@@ -123,7 +158,7 @@ export function createAgentAutocompleteProvider(
 			});
 
 			if (items.length === 0 && !hasCompatibleBaseSuggestions) return baseSuggestions;
-			return { items, prefix: `@${query}` };
+			return { items, prefix };
 		},
 
 		applyCompletion(
@@ -177,16 +212,13 @@ export default function agentAutocompleteExtension(pi: ExtensionAPI): void {
 		sessionGeneration++;
 	});
 
-	// Inject instruction when user types @agent-name (not @session:) in prompt.
-	// Supports multiple different subagents in a single prompt.
-	const AGENT_PROMPT_PATTERN = /(?:^|[\s])@([^\s:@][^\s:]*)/g;
+	// Inject as a request message, not systemPrompt, so the cached prefix stays stable.
 	pi.on("before_agent_start", async (event, _ctx) => {
 		const agents = getAgents();
 		if (agents.length === 0) return;
 
 		const mentions: string[] = [];
-		for (const m of event.prompt.matchAll(AGENT_PROMPT_PATTERN)) {
-			const name = m[1]!;
+		for (const name of extractSubagentReferenceNames(event.prompt)) {
 			if (agents.some((a) => a.name === name) && !mentions.includes(name)) {
 				mentions.push(name);
 			}
@@ -197,12 +229,15 @@ export default function agentAutocompleteExtension(pi: ExtensionAPI): void {
 		const agentList = mentions.map((n) => `"${n}" (${agentMap.get(n)!.displayName})`).join(", ");
 
 		return {
-			systemPrompt:
-				event.systemPrompt +
-				`\n\nThe user's prompt references these subagent types: ${agentList}. ` +
-				`You MUST use the Agent tool for EACH mentioned subagent to delegate the relevant parts of the request. ` +
-				`Handle different subagents separately — do NOT merge their tasks into a single Agent call. ` +
-				`For example, if the user mentions @coder and @explore, make two separate Agent tool calls, one with subagent_type="coder" and another with subagent_type="explore".`,
+			message: {
+				customType: SUBAGENT_DELEGATION_CUSTOM_TYPE,
+				content:
+					`The user's prompt references these subagent types: ${agentList}. ` +
+					`You MUST use the Agent tool for EACH mentioned subagent to delegate the relevant parts of the request. ` +
+					`Handle different subagents separately — do NOT merge their tasks into a single Agent call. ` +
+					`For example, if the user mentions @subagent:[coder] and @subagent:[explore], make two separate Agent tool calls, one with subagent_type="coder" and another with subagent_type="explore".`,
+				display: false,
+			},
 		};
 	});
 }