@oh-my-pi/pi-coding-agent 13.12.6 → 13.12.8

package/src/sdk.ts

@@ -65,6 +65,11 @@ import {
 } from "./internal-urls";
 import { disposeAllKernelSessions } from "./ipy/executor";
 import { discoverAndLoadMCPTools, type MCPManager, type MCPToolsLoadResult } from "./mcp";
+import {
+	collectDiscoverableMCPTools,
+	formatDiscoverableMCPToolServerSummary,
+	summarizeDiscoverableMCPTools,
+} from "./mcp/discoverable-tool-metadata";
 import { buildMemoryToolDeveloperInstructions, getMemoryRoot, startMemoryStartupTask } from "./memories";
 import asyncResultTemplate from "./prompts/tools/async-result.md" with { type: "text" };
 import { collectEnvSecrets, loadSecrets, obfuscateMessages, SecretObfuscator } from "./secrets";
@@ -76,6 +81,7 @@ import { closeAllConnections } from "./ssh/connection-manager";
 import { unmountAll } from "./ssh/sshfs-mount";
 import {
 	buildSystemPrompt as buildSystemPromptInternal,
+	buildSystemPromptToolMetadata,
 	loadProjectContextFiles as loadContextFilesInternal,
 } from "./system-prompt";
 import { AgentOutputManager } from "./task/output-manager";
@@ -95,6 +101,7 @@ import {
 	PythonTool,
 	ReadTool,
 	ResolveTool,
+	renderSearchToolBm25Description,
 	setPreferredCodeSearchProvider,
 	setPreferredImageProvider,
 	setPreferredSearchProvider,
@@ -184,7 +191,7 @@ export interface CreateAgentSessionOptions {
 	/** Parent task ID prefix for nested artifact naming (e.g., "6-Extensions") */
 	parentTaskPrefix?: string;
 
-	/** Session manager. Default: SessionManager.create(cwd) */
+	/** Session manager. Default: session stored under the configured agentDir sessions root */
 	sessionManager?: SessionManager;
 
 	/** Settings instance. Default: Settings.init({ cwd, agentDir }) */
@@ -649,7 +656,11 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		setPreferredImageProvider(imageProvider);
 	}
 
-	const sessionManager = options.sessionManager ?? logger.time("sessionManager", SessionManager.create, cwd);
+	const sessionManager =
+		options.sessionManager ??
+		logger.time("sessionManager", () =>
+			SessionManager.create(cwd, SessionManager.getDefaultSessionDir(cwd, agentDir)),
+		);
 	const sessionId = sessionManager.getSessionId();
 	const modelApiKeyAvailability = new Map<string, boolean>();
 	const getModelAvailabilityKey = (candidate: Model): string =>
@@ -864,6 +875,11 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		getCompactContext: () => session.formatCompactContext(),
 		getTodoPhases: () => session.getTodoPhases(),
 		setTodoPhases: phases => session.setTodoPhases(phases),
+		isMCPDiscoveryEnabled: () => session.isMCPDiscoveryEnabled(),
+		getDiscoverableMCPTools: () => session.getDiscoverableMCPTools(),
+		getDiscoverableMCPSearchIndex: () => session.getDiscoverableMCPSearchIndex(),
+		getSelectedMCPToolNames: () => session.getSelectedMCPToolNames(),
+		activateDiscoveredMCPTools: toolNames => session.activateDiscoveredMCPTools(toolNames),
 		getCheckpointState: () => session.getCheckpointState(),
 		setCheckpointState: state => session.setCheckpointState(state ?? undefined),
 		allocateOutputArtifact: async toolType => {
@@ -1189,6 +1205,13 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	const intentField = settings.get("tools.intentTracing") || $env.PI_INTENT_TRACING === "1" ? INTENT_FIELD : undefined;
 	const rebuildSystemPrompt = async (toolNames: string[], tools: Map<string, AgentTool>): Promise<string> => {
 		toolContextStore.setToolNames(toolNames);
+		const discoverableMCPTools = mcpDiscoveryEnabled ? collectDiscoverableMCPTools(tools.values()) : [];
+		const discoverableMCPSummary = summarizeDiscoverableMCPTools(discoverableMCPTools);
+		const hasDiscoverableMCPTools =
+			mcpDiscoveryEnabled && toolNames.includes("search_tool_bm25") && discoverableMCPTools.length > 0;
+		const promptTools = buildSystemPromptToolMetadata(tools, {
+			search_tool_bm25: { description: renderSearchToolBm25Description(discoverableMCPTools) },
+		});
 		const memoryInstructions = await buildMemoryToolDeveloperInstructions(agentDir, settings);
 
 		// Build combined append prompt: memory instructions + MCP server instructions
@@ -1214,14 +1237,16 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			cwd,
 			skills,
 			contextFiles,
-			tools,
+			tools: promptTools,
 			toolNames,
 			rules: rulebookRules,
 			skillsSettings: settings.getGroup("skills"),
 			appendSystemPrompt: appendPrompt,
 			repeatToolDescriptions,
-			eagerTasks,
 			intentField,
+			mcpDiscoveryMode: hasDiscoverableMCPTools,
+			mcpDiscoveryServerSummaries: discoverableMCPSummary.servers.map(formatDiscoverableMCPToolServerSummary),
+			eagerTasks,
 		});
 
 		if (options.systemPrompt === undefined) {
@@ -1232,15 +1257,17 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				cwd,
 				skills,
 				contextFiles,
-				tools,
+				tools: promptTools,
 				toolNames,
 				rules: rulebookRules,
 				skillsSettings: settings.getGroup("skills"),
 				customPrompt: options.systemPrompt,
 				appendSystemPrompt: appendPrompt,
 				repeatToolDescriptions,
-				eagerTasks,
 				intentField,
+				mcpDiscoveryMode: hasDiscoverableMCPTools,
+				mcpDiscoveryServerSummaries: discoverableMCPSummary.servers.map(formatDiscoverableMCPToolServerSummary),
+				eagerTasks,
 			});
 		}
 		return options.systemPrompt(defaultPrompt);
@@ -1250,9 +1277,17 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	const requestedToolNames = options.toolNames?.map(name => name.toLowerCase()) ?? toolNamesFromRegistry;
 	const normalizedRequested = requestedToolNames.filter(name => toolRegistry.has(name));
 	const includeExitPlanMode = requestedToolNames.includes("exit_plan_mode");
-	const initialToolNames = includeExitPlanMode
+	const mcpDiscoveryEnabled = settings.get("mcp.discoveryMode") ?? false;
+	const requestedActiveToolNames = includeExitPlanMode
 		? normalizedRequested
 		: normalizedRequested.filter(name => name !== "exit_plan_mode");
+	const explicitlyRequestedMCPToolNames = options.toolNames
+		? requestedActiveToolNames.filter(name => name.startsWith("mcp_"))
+		: [];
+	const initialToolNames = mcpDiscoveryEnabled
+		? [...requestedActiveToolNames.filter(name => !name.startsWith("mcp_")), ...explicitlyRequestedMCPToolNames]
+		: [...requestedActiveToolNames];
+	const initialSelectedMCPToolNames = mcpDiscoveryEnabled ? [...explicitlyRequestedMCPToolNames] : [];
 
 	// Custom tools and extension-registered tools are always included regardless of toolNames filter
 	const alwaysInclude: string[] = [
@@ -1260,6 +1295,9 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		...registeredTools.map(t => t.definition.name),
 	];
 	for (const name of alwaysInclude) {
+		if (mcpDiscoveryEnabled && name.startsWith("mcp_")) {
+			continue;
+		}
 		if (toolRegistry.has(name) && !initialToolNames.includes(name)) {
 			initialToolNames.push(name);
 		}
@@ -1440,6 +1478,8 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		onPayload,
 		convertToLlm: convertToLlmFinal,
 		rebuildSystemPrompt,
+		mcpDiscoveryEnabled,
+		initialSelectedMCPToolNames,
 		ttsrManager,
 		obfuscator,
 		asyncJobManager,

package/src/session/agent-session.ts

@@ -87,6 +87,13 @@ import type { Skill, SkillWarning } from "../extensibility/skills";
 import { expandSlashCommand, type FileSlashCommand } from "../extensibility/slash-commands";
 import { resolveLocalUrlToPath } from "../internal-urls";
 import { executePython as executePythonCommand, type PythonResult } from "../ipy/executor";
+import {
+	buildDiscoverableMCPSearchIndex,
+	collectDiscoverableMCPTools,
+	type DiscoverableMCPSearchIndex,
+	type DiscoverableMCPTool,
+	isMCPToolName,
+} from "../mcp/discoverable-tool-metadata";
 import { getCurrentThemeName, theme } from "../modes/theme/theme";
 import { normalizeDiff, normalizeToLF, ParseError, previewPatch, stripBom } from "../patch";
 import type { PlanModeState } from "../plan-mode/state";
@@ -206,6 +213,10 @@ export interface AgentSessionConfig {
 	convertToLlm?: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
 	/** System prompt builder that can consider tool availability */
 	rebuildSystemPrompt?: (toolNames: string[], tools: Map<string, AgentTool>) => Promise<string>;
+	/** Enable hidden-by-default MCP tool discovery for this session. */
+	mcpDiscoveryEnabled?: boolean;
+	/** MCP tool names previously selected via discovery in this session. */
+	initialSelectedMCPToolNames?: string[];
 	/** TTSR manager for time-traveling stream rules */
 	ttsrManager?: TtsrManager;
 	/** Secret obfuscator for deobfuscating streaming edit content */
@@ -400,6 +411,10 @@ export class AgentSession {
 	#convertToLlm: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
 	#rebuildSystemPrompt: ((toolNames: string[], tools: Map<string, AgentTool>) => Promise<string>) | undefined;
 	#baseSystemPrompt: string;
+	#mcpDiscoveryEnabled = false;
+	#discoverableMCPTools = new Map<string, DiscoverableMCPTool>();
+	#discoverableMCPSearchIndex: DiscoverableMCPSearchIndex | null = null;
+	#selectedMCPToolNames = new Set<string>();
 
 	// TTSR manager for time-traveling stream rules
 	#ttsrManager: TtsrManager | undefined = undefined;
@@ -446,6 +461,10 @@ export class AgentSession {
 		this.#convertToLlm = config.convertToLlm ?? convertToLlm;
 		this.#rebuildSystemPrompt = config.rebuildSystemPrompt;
 		this.#baseSystemPrompt = this.agent.state.systemPrompt;
+		this.#mcpDiscoveryEnabled = config.mcpDiscoveryEnabled ?? false;
+		this.#setDiscoverableMCPTools(this.#collectDiscoverableMCPToolsFromRegistry());
+		this.#selectedMCPToolNames = new Set(config.initialSelectedMCPToolNames ?? []);
+		this.#pruneSelectedMCPToolNames();
 		this.#ttsrManager = config.ttsrManager;
 		this.#obfuscator = config.obfuscator;
 		this.agent.providerSessionState = this.#providerSessionState;
@@ -1604,6 +1623,36 @@ export class AgentSession {
 		return this.#retryAttempt;
 	}
 
+	#collectDiscoverableMCPToolsFromRegistry(): Map<string, DiscoverableMCPTool> {
+		return new Map(collectDiscoverableMCPTools(this.#toolRegistry.values()).map(tool => [tool.name, tool] as const));
+	}
+
+	#setDiscoverableMCPTools(discoverableMCPTools: Map<string, DiscoverableMCPTool>): void {
+		this.#discoverableMCPTools = discoverableMCPTools;
+		this.#discoverableMCPSearchIndex = null;
+	}
+
+	#pruneSelectedMCPToolNames(): void {
+		for (const name of Array.from(this.#selectedMCPToolNames)) {
+			if (!this.#discoverableMCPTools.has(name) || !this.#toolRegistry.has(name)) {
+				this.#selectedMCPToolNames.delete(name);
+			}
+		}
+	}
+
+	#getVisibleMCPToolNames(): string[] {
+		if (!this.#mcpDiscoveryEnabled) {
+			return Array.from(this.#toolRegistry.keys()).filter(name => isMCPToolName(name));
+		}
+		return Array.from(this.#selectedMCPToolNames).filter(
+			name => this.#discoverableMCPTools.has(name) && this.#toolRegistry.has(name),
+		);
+	}
+
+	#getActiveNonMCPToolNames(): string[] {
+		return this.getActiveToolNames().filter(name => !isMCPToolName(name) && this.#toolRegistry.has(name));
+	}
+
 	/**
 	 * Get the names of currently active tools.
 	 * Returns the names of tools currently set on the agent.
@@ -1631,11 +1680,52 @@ export class AgentSession {
 		return Array.from(this.#toolRegistry.keys());
 	}
 
+	isMCPDiscoveryEnabled(): boolean {
+		return this.#mcpDiscoveryEnabled;
+	}
+
+	getDiscoverableMCPTools(): DiscoverableMCPTool[] {
+		return Array.from(this.#discoverableMCPTools.values());
+	}
+
+	getDiscoverableMCPSearchIndex(): DiscoverableMCPSearchIndex {
+		if (!this.#discoverableMCPSearchIndex) {
+			this.#discoverableMCPSearchIndex = buildDiscoverableMCPSearchIndex(this.#discoverableMCPTools.values());
+		}
+		return this.#discoverableMCPSearchIndex;
+	}
+
+	getSelectedMCPToolNames(): string[] {
+		if (!this.#mcpDiscoveryEnabled) {
+			return this.getActiveToolNames().filter(name => isMCPToolName(name) && this.#toolRegistry.has(name));
+		}
+		return Array.from(this.#selectedMCPToolNames).filter(
+			name => this.#discoverableMCPTools.has(name) && this.#toolRegistry.has(name),
+		);
+	}
+
+	async activateDiscoveredMCPTools(toolNames: string[]): Promise<string[]> {
+		const activated: string[] = [];
+		for (const name of toolNames) {
+			if (!isMCPToolName(name) || !this.#discoverableMCPTools.has(name) || !this.#toolRegistry.has(name)) {
+				continue;
+			}
+			this.#selectedMCPToolNames.add(name);
+			activated.push(name);
+		}
+		if (activated.length === 0) {
+			return [];
+		}
+		const nextActive = [...this.#getActiveNonMCPToolNames(), ...this.#getVisibleMCPToolNames()];
+		await this.setActiveToolsByName(nextActive);
+		return [...new Set(activated)];
+	}
+
 	/**
 	 * Set active tools by name.
 	 * Only tools in the registry can be enabled. Unknown tool names are ignored.
 	 * Also rebuilds the system prompt to reflect the new tool set.
-	 * Changes take effect on the next agent turn.
+	 * Changes take effect before the next model call.
 	 */
 	async setActiveToolsByName(toolNames: string[]): Promise<void> {
 		const tools: AgentTool[] = [];
@@ -1647,6 +1737,13 @@ export class AgentSession {
 				validToolNames.push(name);
 			}
 		}
+		if (this.#mcpDiscoveryEnabled) {
+			this.#selectedMCPToolNames = new Set(
+				validToolNames.filter(
+					name => isMCPToolName(name) && this.#discoverableMCPTools.has(name) && this.#toolRegistry.has(name),
+				),
+			);
+		}
 		this.agent.setTools(tools);
 
 		// Rebuild base system prompt with new tool set
@@ -1665,14 +1762,13 @@ export class AgentSession {
 	}
 
 	/**
-	 * Replace MCP tools in the registry and activate the latest MCP tool set immediately.
+	 * Replace MCP tools in the registry and recompute the visible MCP tool set immediately.
 	 * This allows /mcp add/remove/reauth to take effect without restarting the session.
 	 */
 	async refreshMCPTools(mcpTools: CustomTool[]): Promise<void> {
-		const prefix = "mcp_";
 		const existingNames = Array.from(this.#toolRegistry.keys());
 		for (const name of existingNames) {
-			if (name.startsWith(prefix)) {
+			if (isMCPToolName(name)) {
 				this.#toolRegistry.delete(name);
 			}
 		}
@@ -1696,17 +1792,10 @@ export class AgentSession {
 			this.#toolRegistry.set(finalTool.name, finalTool);
 		}
 
-		const currentActive = this.getActiveToolNames().filter(
-			name => !name.startsWith(prefix) && this.#toolRegistry.has(name),
-		);
-		const mcpToolNames = Array.from(this.#toolRegistry.keys()).filter(name => name.startsWith(prefix));
-		const nextActive = [...currentActive];
-		for (const name of mcpToolNames) {
-			if (!nextActive.includes(name)) {
-				nextActive.push(name);
-			}
-		}
+		this.#setDiscoverableMCPTools(this.#collectDiscoverableMCPToolsFromRegistry());
+		this.#pruneSelectedMCPToolNames();
 
+		const nextActive = [...this.#getActiveNonMCPToolNames(), ...this.getSelectedMCPToolNames()];
 		await this.setActiveToolsByName(nextActive);
 	}
 

package/src/session/session-manager.ts

@@ -21,6 +21,8 @@ import {
 	isEnoent,
 	logger,
 	parseJsonlLenient,
+	pathIsWithin,
+	resolveEquivalentPath,
 	Snowflake,
 	toError,
 } from "@oh-my-pi/pi-utils";
@@ -345,7 +347,7 @@ export function migrateSessionEntries(entries: FileEntry[]): void {
 	migrateToCurrentVersion(entries);
 }
 
-let sessionDirsMigrated = false;
+const migratedSessionRoots = new Set<string>();
 
 /**
  * Merge or rename a legacy session directory into its canonical target.
@@ -375,29 +377,36 @@ function encodeLegacyAbsoluteSessionDirName(cwd: string): string {
 	return `--${resolvedCwd.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-")}--`;
 }
 
-function pathIsWithin(root: string, candidate: string): boolean {
-	const relative = path.relative(root, candidate);
-	return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
-}
-
 function encodeRelativeSessionDirName(prefix: string, root: string, cwd: string): string {
 	const relative = path.relative(root, cwd).replace(/[/\\:]/g, "-");
-	return relative ? `${prefix}-${relative}` : prefix;
+	return relative ? (prefix.endsWith("-") ? `${prefix}${relative}` : `${prefix}-${relative}`) : prefix;
+}
+
+function getDefaultSessionDirName(cwd: string): { encodedDirName: string; resolvedCwd: string } {
+	const resolvedCwd = path.resolve(cwd);
+	const canonicalCwd = resolveEquivalentPath(resolvedCwd);
+	const home = resolveEquivalentPath(os.homedir());
+	const tempRoot = resolveEquivalentPath(os.tmpdir());
+	const encodedDirName = pathIsWithin(home, canonicalCwd)
+		? encodeRelativeSessionDirName("-", home, canonicalCwd)
+		: pathIsWithin(tempRoot, canonicalCwd)
+			? encodeRelativeSessionDirName("-tmp", tempRoot, canonicalCwd)
+			: encodeLegacyAbsoluteSessionDirName(canonicalCwd);
+	return { encodedDirName, resolvedCwd };
 }
 
 /**
  * Migrate old `--<home-encoded>-*--` session dirs to the new `-*` format.
- * Runs once on first access, best-effort.
+ * Runs once per sessions root on first access, best-effort.
  */
-function migrateHomeSessionDirs(): void {
-	if (sessionDirsMigrated) return;
-	sessionDirsMigrated = true;
+function migrateHomeSessionDirs(sessionsRoot: string): void {
+	if (migratedSessionRoots.has(sessionsRoot)) return;
+	migratedSessionRoots.add(sessionsRoot);
 
 	const home = os.homedir();
 	const homeEncoded = home.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-");
 	const oldPrefix = `--${homeEncoded}-`;
 	const oldExact = `--${homeEncoded}--`;
-	const sessionsRoot = getSessionsDir();
 
 	let entries: string[];
 	try {
@@ -428,8 +437,8 @@ function migrateHomeSessionDirs(): void {
 	}
 }
 
-function migrateLegacyAbsoluteSessionDir(cwd: string, sessionDir: string): void {
-	const legacyDir = path.join(getSessionsDir(), encodeLegacyAbsoluteSessionDirName(cwd));
+function migrateLegacyAbsoluteSessionDir(cwd: string, sessionDir: string, sessionsRoot: string): void {
+	const legacyDir = path.join(sessionsRoot, encodeLegacyAbsoluteSessionDirName(cwd));
 	if (legacyDir === sessionDir || !fs.existsSync(legacyDir)) return;
 
 	try {
@@ -439,6 +448,15 @@ function migrateLegacyAbsoluteSessionDir(cwd: string, sessionDir: string): void
 	}
 }
 
+function resolveManagedSessionRoot(sessionDir: string, cwd: string): string | undefined {
+	const currentDirName = path.basename(sessionDir);
+	const { encodedDirName } = getDefaultSessionDirName(cwd);
+	if (currentDirName !== encodedDirName && currentDirName !== encodeLegacyAbsoluteSessionDirName(cwd)) {
+		return undefined;
+	}
+	return path.dirname(sessionDir);
+}
+
 /** Exported for compaction.test.ts */
 export function parseSessionEntries(content: string): FileEntry[] {
 	return parseJsonlLenient<FileEntry>(content);
@@ -633,34 +651,20 @@ export function buildSessionContext(
 	return { messages, thinkingLevel, serviceTier, models, injectedTtsrRules, mode, modeData };
 }
 
-/**
- * Encode a cwd into a safe directory name for session storage.
- * Home-relative paths use single-dash format: `/Users/x/Projects/pi` → `-Projects-pi`
- * Temp-root paths use `-tmp-` prefixes: `/tmp/foo` → `-tmp-foo`
- * Other absolute paths keep the legacy double-dash format for compatibility.
- */
-function encodeSessionDirName(cwd: string): string {
-	const resolvedCwd = path.resolve(cwd);
-	const home = path.resolve(os.homedir());
-	if (pathIsWithin(home, resolvedCwd)) {
-		return encodeRelativeSessionDirName("-", home, resolvedCwd);
-	}
-	const tempRoot = path.resolve(os.tmpdir());
-	if (pathIsWithin(tempRoot, resolvedCwd)) {
-		return encodeRelativeSessionDirName("-tmp", tempRoot, resolvedCwd);
-	}
-	return encodeLegacyAbsoluteSessionDirName(resolvedCwd);
-}
-
 /**
  * Compute the default session directory for a cwd.
- * Encodes cwd into a safe directory name under ~/.omp/agent/sessions/.
+ * Classifies cwd by canonical location so symlink/alias paths resolve to the
+ * same home-relative or temp-root directory names as their real targets.
  */
-function getDefaultSessionDir(cwd: string, storage: SessionStorage): string {
-	const resolvedCwd = path.resolve(cwd);
-	migrateHomeSessionDirs();
-	const sessionDir = path.join(getSessionsDir(), encodeSessionDirName(resolvedCwd));
-	migrateLegacyAbsoluteSessionDir(resolvedCwd, sessionDir);
+function computeDefaultSessionDir(
+	cwd: string,
+	storage: SessionStorage,
+	sessionsRoot: string = getSessionsDir(),
+): string {
+	const { encodedDirName, resolvedCwd } = getDefaultSessionDirName(cwd);
+	migrateHomeSessionDirs(sessionsRoot);
+	const sessionDir = path.join(sessionsRoot, encodedDirName);
+	migrateLegacyAbsoluteSessionDir(resolvedCwd, sessionDir, sessionsRoot);
 	storage.ensureDirSync(sessionDir);
 	return sessionDir;
 }
@@ -1322,7 +1326,8 @@ export async function resolveResumableSession(
 	sessionDir?: string,
 	storage: SessionStorage = new FileSessionStorage(),
 ): Promise<ResolvedSessionMatch | undefined> {
-	const localSessions = await SessionManager.list(cwd, sessionDir, storage);
+	const localSessionDir = sessionDir ?? SessionManager.getDefaultSessionDir(cwd, undefined, storage);
+	const localSessions = await SessionManager.list(cwd, localSessionDir, storage);
 	const localMatch = localSessions.find(session => sessionMatchesResumeArg(session, sessionArg));
 	if (localMatch) {
 		return { session: localMatch, scope: "local" };
@@ -1489,7 +1494,10 @@ export class SessionManager {
 		const resolvedCwd = path.resolve(newCwd);
 		if (resolvedCwd === this.cwd) return;
 
-		const newSessionDir = getDefaultSessionDir(resolvedCwd, this.storage);
+		const managedSessionsRoot = resolveManagedSessionRoot(this.sessionDir, this.cwd);
+		const newSessionDir = managedSessionsRoot
+			? computeDefaultSessionDir(resolvedCwd, this.storage, managedSessionsRoot)
+			: computeDefaultSessionDir(resolvedCwd, this.storage);
 		let hadSessionFile = false;
 
 		if (this.persist && this.#sessionFile) {
@@ -2446,13 +2454,24 @@ export class SessionManager {
 		return undefined;
 	}
 
+	/**
+	 * Resolve the canonical default session directory for a cwd.
+	 */
+	static getDefaultSessionDir(
+		cwd: string,
+		agentDir?: string,
+		storage: SessionStorage = new FileSessionStorage(),
+	): string {
+		return computeDefaultSessionDir(cwd, storage, getSessionsDir(agentDir));
+	}
+
 	/**
 	 * Create a new session.
 	 * @param cwd Working directory (stored in session header)
 	 * @param sessionDir Optional session directory. If omitted, uses default (~/.omp/agent/sessions/<encoded-cwd>/).
 	 */
 	static create(cwd: string, sessionDir?: string, storage: SessionStorage = new FileSessionStorage()): SessionManager {
-		const dir = sessionDir ?? getDefaultSessionDir(cwd, storage);
+		const dir = sessionDir ?? SessionManager.getDefaultSessionDir(cwd, undefined, storage);
 		const manager = new SessionManager(cwd, dir, true, storage);
 		manager.#initNewSession();
 		return manager;
@@ -2468,7 +2487,7 @@ export class SessionManager {
 		sessionDir?: string,
 		storage: SessionStorage = new FileSessionStorage(),
 	): Promise<SessionManager> {
-		const dir = sessionDir ?? getDefaultSessionDir(cwd, storage);
+		const dir = sessionDir ?? SessionManager.getDefaultSessionDir(cwd, undefined, storage);
 		const manager = new SessionManager(cwd, dir, true, storage);
 		const forkEntries = structuredClone(await loadEntriesFromFile(sourcePath, storage)) as FileEntry[];
 		migrateToCurrentVersion(forkEntries);
@@ -2516,7 +2535,7 @@ export class SessionManager {
 		sessionDir?: string,
 		storage: SessionStorage = new FileSessionStorage(),
 	): Promise<SessionManager> {
-		const dir = sessionDir ?? getDefaultSessionDir(cwd, storage);
+		const dir = sessionDir ?? SessionManager.getDefaultSessionDir(cwd, undefined, storage);
 		// Prefer terminal-scoped breadcrumb (handles concurrent sessions correctly)
 		const terminalSession = await readTerminalBreadcrumb(cwd);
 		const mostRecent = terminalSession ?? (await findMostRecentSession(dir, storage));
@@ -2549,7 +2568,7 @@ export class SessionManager {
 		sessionDir?: string,
 		storage: SessionStorage = new FileSessionStorage(),
 	): Promise<SessionInfo[]> {
-		const dir = sessionDir ?? getDefaultSessionDir(cwd, storage);
+		const dir = sessionDir ?? SessionManager.getDefaultSessionDir(cwd, undefined, storage);
 		try {
 			const files = storage.listFilesSync(dir, "*.jsonl");
 			return await collectSessionsFromFiles(files, storage);

package/src/system-prompt.ts

@@ -5,6 +5,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import type { AgentTool } from "@oh-my-pi/pi-agent-core";
 import { $env, getGpuCachePath, getProjectDir, hasFsCode, isEnoent, logger } from "@oh-my-pi/pi-utils";
 import { $ } from "bun";
 import { contextFileCapability } from "./capability/context-file";
@@ -315,11 +316,36 @@ export async function loadSystemPromptFiles(options: LoadContextFilesOptions = {
 	return parts.join("\n\n");
 }
 
+export interface SystemPromptToolMetadata {
+	label: string;
+	description: string;
+}
+
+export function buildSystemPromptToolMetadata(
+	tools: Map<string, AgentTool>,
+	overrides: Partial<Record<string, Partial<SystemPromptToolMetadata>>> = {},
+): Map<string, SystemPromptToolMetadata> {
+	return new Map(
+		Array.from(tools.entries(), ([name, tool]) => {
+			const toolRecord = tool as AgentTool & { label?: string; description?: string };
+			const override = overrides[name];
+			return [
+				name,
+				{
+					label: override?.label ?? (typeof toolRecord.label === "string" ? toolRecord.label : ""),
+					description:
+						override?.description ?? (typeof toolRecord.description === "string" ? toolRecord.description : ""),
+				},
+			] as const;
+		}),
+	);
+}
+
 export interface BuildSystemPromptOptions {
 	/** Custom system prompt (replaces default). */
 	customPrompt?: string;
 	/** Tools to include in prompt. */
-	tools?: Map<string, { description: string; label: string }>;
+	tools?: Map<string, SystemPromptToolMetadata>;
 	/** Tool names to include in prompt. */
 	toolNames?: string[];
 	/** Text to append to system prompt. */
@@ -338,6 +364,10 @@ export interface BuildSystemPromptOptions {
 	rules?: Array<{ name: string; description?: string; path: string; globs?: string[] }>;
 	/** Intent field name injected into every tool schema. If set, explains the field in the prompt. */
 	intentField?: string;
+	/** Whether MCP tool discovery is active for this prompt build. */
+	mcpDiscoveryMode?: boolean;
+	/** Discoverable MCP server summaries to advertise when discovery mode is active. */
+	mcpDiscoveryServerSummaries?: string[];
 	/** Encourage the agent to delegate via tasks unless changes are trivial. */
 	eagerTasks?: boolean;
 }
@@ -360,6 +390,8 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		skills: providedSkills,
 		rules,
 		intentField,
+		mcpDiscoveryMode = false,
+		mcpDiscoveryServerSummaries = [],
 		eagerTasks = false,
 	} = options;
 	const resolvedCwd = cwd ?? getProjectDir();
@@ -494,6 +526,9 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		cwd: promptCwd,
 		intentTracing: !!intentField,
 		intentField: intentField ?? "",
+		mcpDiscoveryMode,
+		hasMCPDiscoveryServers: mcpDiscoveryServerSummaries.length > 0,
+		mcpDiscoveryServerSummaries,
 		eagerTasks,
 	};
 	return renderPromptTemplate(resolvedCustomPrompt ? customSystemPromptTemplate : systemPromptTemplate, data);

package/src/tools/ast-edit.ts

@@ -17,6 +17,7 @@ import type { OutputMeta } from "./output-meta";
 import {
 	combineSearchGlobs,
 	hasGlobPathChars,
+	normalizePathLikeInput,
 	parseSearchPath,
 	resolveMultiSearchPath,
 	resolveToCwd,
@@ -110,8 +111,8 @@ export class AstEditTool implements AgentTool<typeof astEditSchema, AstEditToolD
 			};
 			let searchPath: string | undefined;
 			let scopePath: string | undefined;
-			let globFilter = params.glob?.trim() || undefined;
-			const rawPath = params.path?.trim();
+			let globFilter = params.glob ? normalizePathLikeInput(params.glob) || undefined : undefined;
+			const rawPath = params.path ? normalizePathLikeInput(params.path) || undefined : undefined;
 			if (rawPath) {
 				const internalRouter = this.session.internalRouter;
 				if (internalRouter?.canHandle(rawPath)) {