@oh-my-pi/pi-coding-agent 15.10.11 → 15.11.0

package/src/config/settings.ts

@@ -64,6 +64,8 @@ export interface SettingsOptions {
 	inMemory?: boolean;
 	/** Initial overrides */
 	overrides?: Partial<Record<SettingPath, unknown>>;
+	/** Extra config.yml-style overlays loaded after global/project settings */
+	configFiles?: string[];
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -116,10 +118,12 @@ type PathScopedStringArrayEntry = {
 	providers?: unknown;
 };
 
+function expandTilde(p: string): string {
+	return p === "~" ? os.homedir() : p.startsWith("~/") ? path.join(os.homedir(), p.slice(2)) : p;
+}
+
 function normalizePathPrefix(prefix: string): string {
-	const expanded =
-		prefix === "~" ? os.homedir() : prefix.startsWith("~/") ? path.join(os.homedir(), prefix.slice(2)) : prefix;
-	return path.resolve(expanded);
+	return path.resolve(expandTilde(prefix));
 }
 
 function pathMatchesPrefix(cwd: string, prefix: string): boolean {
@@ -193,10 +197,13 @@ export class Settings {
 	#agentDir: string;
 	#storage: AgentStorage | null = null;
 
+	#configFiles: string[] = [];
 	/** Global settings from config.yml */
 	#global: RawSettings = {};
 	/** Project settings from .claude/settings.yml etc */
 	#project: RawSettings = {};
+	/** Extra config.yml-style overlays passed by CLI */
+	#configOverlay: RawSettings = {};
 	/** Runtime overrides (not persisted) */
 	#overrides: RawSettings = {};
 	/** Merged view (global + project + overrides) */
@@ -221,6 +228,7 @@ export class Settings {
 		this.#cwd = path.normalize(options.cwd ?? getProjectDir());
 		this.#agentDir = path.normalize(options.agentDir ?? getAgentDir());
 		this.#configPath = options.inMemory ? null : path.join(this.#agentDir, "config.yml");
+		this.#configFiles = options.configFiles?.map(file => path.resolve(this.#cwd, expandTilde(file))) ?? [];
 		this.#persist = !options.inMemory;
 
 		if (options.overrides) {
@@ -256,6 +264,7 @@ export class Settings {
 			},
 			error => {
 				globalInstance = null;
+				globalInstancePromise = null;
 				clearBoundSettingsMethods();
 				throw error;
 			},
@@ -303,6 +312,14 @@ export class Settings {
 		return resolved as SettingValue<P>;
 	}
 
+	/**
+	 * Whether `path` has an explicitly configured value (global config, project
+	 * config, or runtime override) rather than falling back to the schema default.
+	 */
+	isConfigured(path: SettingPath): boolean {
+		return getByPath(this.#merged, SETTING_PATH_SEGMENTS[path]) !== undefined;
+	}
+
 	/**
 	 * Set a setting value (sync).
 	 * Updates global settings and queues a background save.
@@ -386,6 +403,8 @@ export class Settings {
 		cloned.#storage = this.#storage;
 		cloned.#global = structuredClone(this.#global);
 		cloned.#project = this.#persist ? await cloned.#loadProjectSettings() : structuredClone(this.#project);
+		cloned.#configFiles = [...this.#configFiles];
+		cloned.#configOverlay = structuredClone(this.#configOverlay);
 		cloned.#overrides = structuredClone(this.#overrides);
 		cloned.#rebuildMerged();
 		cloned.#fireAllHooks();
@@ -557,6 +576,7 @@ export class Settings {
 		}
 
 		this.#project = await projectPromise;
+		this.#configOverlay = await this.#loadConfigOverlays();
 
 		// Build merged view (global → project → overrides; project wins over global)
 		this.#rebuildMerged();
@@ -594,6 +614,43 @@ export class Settings {
 		}
 	}
 
+	async #loadConfigOverlays(): Promise<RawSettings> {
+		let merged: RawSettings = {};
+		for (const filePath of this.#configFiles) {
+			merged = this.#deepMerge(merged, await this.#loadOverlayYaml(filePath));
+		}
+		return merged;
+	}
+
+	/**
+	 * Strict loader for explicit `--config` overlays: unlike `#loadYaml`,
+	 * missing or malformed files are hard errors so a typo'd path cannot
+	 * silently fall back to the persistent settings.
+	 */
+	async #loadOverlayYaml(filePath: string): Promise<RawSettings> {
+		let content: string;
+		try {
+			content = await Bun.file(filePath).text();
+		} catch (error) {
+			throw new Error(
+				isEnoent(error)
+					? `Config overlay not found: ${filePath}`
+					: `Failed to read config overlay ${filePath}: ${String(error)}`,
+			);
+		}
+		let parsed: unknown;
+		try {
+			parsed = YAML.parse(content);
+		} catch (error) {
+			throw new Error(`Failed to parse config overlay ${filePath}: ${String(error)}`);
+		}
+		if (parsed === null || parsed === undefined) return {};
+		if (typeof parsed !== "object" || Array.isArray(parsed)) {
+			throw new Error(`Config overlay must be a YAML mapping: ${filePath}`);
+		}
+		return this.#migrateRawSettings(parsed as RawSettings);
+	}
+
 	async #migrateFromLegacy(): Promise<void> {
 		if (!this.#configPath) return;
 
@@ -688,6 +745,13 @@ export class Settings {
 			delete isolationObj.enabled;
 		}
 
+		// task.simple: removed — the task tool no longer accepts a per-call
+		// schema (workflows drive structured output via eval agent()) and the
+		// batch/context shape is gated by task.batch instead.
+		if (taskObj && "simple" in taskObj) {
+			delete taskObj.simple;
+		}
+
 		// task.isolation.mode: legacy values from before the pi-iso PAL refactor.
 		// `worktree` was git worktree → now lives under `rcopy`. `fuse-overlay`
 		// and `fuse-projfs` are now the platform-named `overlayfs` / `projfs`
@@ -898,6 +962,7 @@ export class Settings {
 
 	#rebuildMerged(): void {
 		this.#merged = this.#deepMerge(this.#deepMerge({}, this.#global), this.#project);
+		this.#merged = this.#deepMerge(this.#merged, this.#configOverlay);
 		this.#merged = this.#deepMerge(this.#merged, this.#overrides);
 		this.#resolvedCache.clear();
 	}

package/src/edit/hashline/execute.ts

@@ -23,11 +23,13 @@ import type { AgentToolResult } from "@oh-my-pi/pi-agent-core";
 import type { FileDiagnosticsResult, WritethroughCallback, WritethroughDeferredHandle } from "../../lsp";
 import type { ToolSession } from "../../tools";
 import { outputMeta } from "../../tools/output-meta";
+import { ToolError } from "../../tools/tool-errors";
 import { generateDiffString } from "../diff";
 import { getFileSnapshotStore } from "../file-snapshot-store";
 import type { EditToolDetails, EditToolPerFileResult, LspBatchRequest } from "../renderer";
 import { nativeBlockResolver } from "./block-resolver";
 import { HashlineFilesystem } from "./filesystem";
+import { hashPatchInput, NOOP_HARD_LIMIT, recordNoopEdit, resetNoopEdit } from "./noop-loop-guard";
 import { type HashlineParams, hashlineEditParamsSchema } from "./params";
 
 export interface ExecuteHashlineSingleOptions {
@@ -54,6 +56,24 @@ function noChangeDiagnostic(path: string): string {
 	);
 }
 
+/**
+ * Escalated diagnostic surfaced once the same payload has no-op'd
+ * {@link NOOP_HARD_LIMIT} times in a row on the same canonical path. Thrown as
+ * a {@link ToolError} so the agent loop sees a tool *failure* — empirically
+ * far more effective at breaking a no-op edit loop than the soft hint alone
+ * (issue #2081 saw 182 byte-identical no-op results in 205 calls before the
+ * user aborted).
+ */
+function noChangeLoopDiagnostic(path: string, count: number): string {
+	return (
+		`STOP. Edits to ${path} have been a byte-identical no-op ${count} times in a row — ` +
+		`the patch body matches the file at the targeted lines and the soft hint did not break the cycle. ` +
+		`Cease re-issuing this payload. Either the intended change is already on disk (move on), ` +
+		`or your anchor is wrong (re-read the file with \`read\` to observe the current line numbers and ` +
+		`tag, then author a different edit). This exact payload will keep being rejected until it changes.`
+	);
+}
+
 function assertUniqueCanonicalPaths(prepared: readonly PreparedSection[]): void {
 	const seen = new Map<string, string>();
 	for (const entry of prepared) {
@@ -156,13 +176,19 @@ export async function executeHashlineSingle(
 	const patcher = new Patcher({ fs, snapshots, blockResolver: nativeBlockResolver });
 
 	// Single-section fast path: prepare, commit, render.
+	const inputHash = hashPatchInput(options.input);
 	if (patch.sections.length === 1) {
 		fs.setBatchRequest(narrowBatchRequest(options.batchRequest, true));
 		const prepared = await patcher.prepare(patch.sections[0]);
 		const sectionResult = await patcher.commit(prepared);
 		if (sectionResult.op === "noop") {
+			const { count, escalate } = recordNoopEdit(options.session, sectionResult.canonicalPath, inputHash);
+			if (escalate) {
+				throw new ToolError(noChangeLoopDiagnostic(sectionResult.path, count));
+			}
 			return renderSection(sectionResult, undefined).toolResult;
 		}
+		resetNoopEdit(options.session, sectionResult.canonicalPath);
 		return renderSection(sectionResult, fs.consumeDiagnostics(sectionResult.path)).toolResult;
 	}
 
@@ -172,7 +198,12 @@ export async function executeHashlineSingle(
 	for (const section of patch.sections) prepared.push(await patcher.prepare(section));
 	assertUniqueCanonicalPaths(prepared);
 	for (const entry of prepared) {
-		if (entry.isNoop) throw new Error(noChangeDiagnostic(entry.section.path));
+		if (entry.isNoop) {
+			const { count, escalate } = recordNoopEdit(options.session, entry.canonicalPath, inputHash);
+			throw escalate
+				? new ToolError(noChangeLoopDiagnostic(entry.section.path, count))
+				: new ToolError(noChangeDiagnostic(entry.section.path));
+		}
 	}
 	// Then commit each one, narrowing the LSP batch flush flag to the final
 	// section only. A no-op apply mid-batch is treated as a hard failure —
@@ -182,7 +213,13 @@ export async function executeHashlineSingle(
 		const isLast = i === prepared.length - 1;
 		fs.setBatchRequest(narrowBatchRequest(options.batchRequest, isLast));
 		const sectionResult = await patcher.commit(prepared[i]);
-		if (sectionResult.op === "noop") throw new Error(noChangeDiagnostic(sectionResult.path));
+		if (sectionResult.op === "noop") {
+			const { count, escalate } = recordNoopEdit(options.session, sectionResult.canonicalPath, inputHash);
+			throw escalate
+				? new ToolError(noChangeLoopDiagnostic(sectionResult.path, count))
+				: new ToolError(noChangeDiagnostic(sectionResult.path));
+		}
+		resetNoopEdit(options.session, sectionResult.canonicalPath);
 		rendered.push(renderSection(sectionResult, fs.consumeDiagnostics(sectionResult.path)));
 	}
 

package/src/edit/hashline/noop-loop-guard.ts

@@ -0,0 +1,99 @@
+/**
+ * Per-session guard against subagents looping on byte-identical no-op edits.
+ *
+ * A hashline patch can apply cleanly yet produce no change when the body rows
+ * are already byte-identical to the targeted lines. {@link executeHashlineSingle}
+ * surfaces a soft hint ("re-read the file before issuing another edit"), but in
+ * the wild some models ignore the hint and keep re-issuing the same bytes
+ * (issue #2081 captured 182 such repeats in 205 calls before the user aborted).
+ *
+ * This module tracks consecutive byte-identical no-op edits per canonical file
+ * path within a single session. Once the same payload no-ops {@link NOOP_HARD_LIMIT}
+ * times in a row the caller is expected to escalate from a soft text result to
+ * a thrown {@link ToolError} so the agent loop sees a tool *failure* — empirically
+ * far more effective at breaking the cycle than the soft hint alone.
+ *
+ * A successful (non-noop) commit for a path resets that path's counter; a
+ * different payload on the same path also resets it because the body hash
+ * changed, which is a sign of model progress and deserves another soft hint.
+ */
+
+interface NoopLoopEntry {
+	/** Hash of the most recent input that no-op'd on this canonical path. */
+	hash: string;
+	/** Consecutive no-op count for the same `hash` on this path. */
+	count: number;
+}
+
+/** Cross-session-safe state slot held on the `ToolSession`. */
+export interface NoopLoopGuard {
+	entries: Map<string, NoopLoopEntry>;
+}
+
+/**
+ * After this many consecutive byte-identical no-op edits on the same path,
+ * {@link recordNoopEdit} returns `escalate: true`. Picked deliberately small
+ * so the soft hint still fires once or twice before we escalate — the model
+ * deserves a chance to recover, but a tight bound is what actually breaks
+ * loops in practice.
+ */
+export const NOOP_HARD_LIMIT = 3;
+
+interface NoopLoopGuardOwner {
+	noopLoopGuard?: NoopLoopGuard;
+}
+
+/** Lazily create the per-session guard, mirroring `getFileSnapshotStore`. */
+export function getNoopLoopGuard(session: NoopLoopGuardOwner): NoopLoopGuard {
+	if (!session.noopLoopGuard) session.noopLoopGuard = { entries: new Map() };
+	return session.noopLoopGuard;
+}
+
+/** Result of recording one no-op against the guard. */
+export interface NoopRecordResult {
+	/** Consecutive identical no-op count, including the current one. */
+	count: number;
+	/** True once `count >= NOOP_HARD_LIMIT` and the caller MUST escalate. */
+	escalate: boolean;
+}
+
+/**
+ * Record a no-op edit for `canonicalPath` keyed by `inputHash` (a stable hash
+ * of the raw patch input bytes). Returns the running consecutive-no-op count
+ * and whether the caller should escalate from a soft text result to a thrown
+ * error.
+ *
+ * `inputHash` is intentionally derived from the raw model-authored bytes
+ * rather than from file content: when the model emits a different payload
+ * (even whitespace-only) that's progress and earns a fresh soft hint, but
+ * re-issuing the same bytes after being warned is what we want to break.
+ */
+export function recordNoopEdit(
+	session: NoopLoopGuardOwner,
+	canonicalPath: string,
+	inputHash: string,
+): NoopRecordResult {
+	const guard = getNoopLoopGuard(session);
+	const prev = guard.entries.get(canonicalPath);
+	const count = prev && prev.hash === inputHash ? prev.count + 1 : 1;
+	guard.entries.set(canonicalPath, { hash: inputHash, count });
+	return { count, escalate: count >= NOOP_HARD_LIMIT };
+}
+
+/**
+ * Clear the no-op counter for `canonicalPath`. Call after a non-noop commit
+ * for the same path so a future no-op starts fresh from the soft hint.
+ */
+export function resetNoopEdit(session: NoopLoopGuardOwner, canonicalPath: string): void {
+	const guard = session.noopLoopGuard;
+	if (!guard) return;
+	guard.entries.delete(canonicalPath);
+}
+
+/**
+ * Stable hash of the raw patch input. Bun's `Bun.hash` is xxHash64 — fast,
+ * non-cryptographic, more than adequate for "is this the same payload?".
+ */
+export function hashPatchInput(input: string): string {
+	return Bun.hash(input).toString(16);
+}

package/src/eval/__tests__/agent-bridge.test.ts

@@ -99,6 +99,7 @@ function singleResult(options: ExecutorOptions, overrides: Partial<SingleResult>
 		truncated: false,
 		durationMs: 1,
 		tokens: 0,
+		requests: 0,
 		...overrides,
 	};
 }
@@ -178,7 +179,7 @@ describe("runEvalAgent", () => {
 		expect(runSpy).not.toHaveBeenCalled();
 	});
 
-	it("passes the parent execution context and only sets outputSchema when schema is supplied", async () => {
+	it("passes parent execution options and only sets outputSchema when schema is supplied", async () => {
 		mockAgents();
 		const runSpy = vi.spyOn(taskExecutor, "runSubprocess").mockImplementation(async options => singleResult(options));
 		const abortController = new AbortController();
@@ -186,7 +187,7 @@ describe("runEvalAgent", () => {
 		const session = makeSession({ depth: 2, activeModel: "p/current", modelString: "p/fallback" });
 
 		await runEvalAgent(
-			{ prompt: " hello ", context: " context ", label: "My Agent", model: "p/override", schema },
+			{ prompt: " hello ", label: "My Agent", model: "p/override", schema },
 			{ session, signal: abortController.signal },
 		);
 		await runEvalAgent({ prompt: "plain" }, { session });
@@ -199,7 +200,6 @@ describe("runEvalAgent", () => {
 		expect(firstOptions.parentActiveModelPattern).toBe("p/current");
 		expect(firstOptions.outputSchema).toBe(schema);
 		expect(firstOptions.assignment).toBe("hello");
-		expect(firstOptions.context).toBe("context");
 		expect(firstOptions.description).toBe("My Agent");
 		expect(firstOptions.modelOverride).toEqual(["p/override"]);
 		expect(secondOptions.outputSchema).toBeUndefined();
@@ -542,6 +542,7 @@ describe("agent() through eval runtimes", () => {
 			recentOutput: [],
 			toolCount: 0,
 			tokens: 0,
+			requests: 0,
 			cost: 0,
 			durationMs: 0,
 			...overrides,
@@ -674,6 +675,7 @@ describe("agent() through eval runtimes", () => {
 					recentOutput: [],
 					toolCount: i,
 					tokens: 0,
+					requests: 0,
 					cost: 0,
 					durationMs: i * 10,
 				});

package/src/eval/agent-bridge.ts

@@ -34,7 +34,6 @@ const agentArgsSchema = z.object({
 	prompt: z.string().min(1, "prompt must be a non-empty string"),
 	agentType: z.string().min(1).optional(),
 	model: z.union([z.string().min(1), z.array(z.string().min(1)).min(1)]).optional(),
-	context: z.string().optional(),
 	label: z.string().optional(),
 	schema: z.unknown().optional(),
 });
@@ -43,7 +42,6 @@ interface EvalAgentArgs {
 	prompt: string;
 	agentType?: string;
 	model?: string | string[];
-	context?: string;
 	label?: string;
 	schema?: unknown;
 }
@@ -111,7 +109,7 @@ function assertNotPlanMode(session: ToolSession): void {
 }
 
 function renderSubagentPrompt(assignment: string): string {
-	return prompt.render(subagentUserPromptTemplate, { assignment: assignment.trim(), independentMode: false });
+	return prompt.render(subagentUserPromptTemplate, { assignment: assignment.trim() });
 }
 
 function trimToUndefined(value: string | undefined): string | undefined {
@@ -135,20 +133,12 @@ function getOutputManager(session: ToolSession): AgentOutputManager {
 async function getArtifacts(session: ToolSession): Promise<{
 	sessionFile: string | null;
 	artifactsDir: string;
-	contextFile?: string;
 }> {
 	const sessionFile = session.getSessionFile();
 	const sessionArtifactsDir = sessionFile ? sessionFile.slice(0, -6) : null;
 	const artifactsDir = sessionArtifactsDir ?? path.join(os.tmpdir(), `omp-eval-agent-${Snowflake.next()}`);
 	await fs.mkdir(artifactsDir, { recursive: true });
-
-	const shouldWriteConversationContext = session.settings.get("irc.enabled") !== true;
-	const compactContext = shouldWriteConversationContext ? session.getCompactContext?.() : undefined;
-	if (!compactContext) return { sessionFile, artifactsDir };
-
-	const contextFile = path.join(artifactsDir, "context.md");
-	await Bun.write(contextFile, compactContext);
-	return { sessionFile, artifactsDir, contextFile };
+	return { sessionFile, artifactsDir };
 }
 
 function emitProgressStatus(emitStatus: ((event: JsStatusEvent) => void) | undefined, progress: AgentProgress): void {
@@ -246,11 +236,10 @@ export async function runEvalAgent(args: unknown, options: EvalAgentBridgeOption
 	};
 	const parentArtifactManager = options.session.getArtifactManager?.() ?? undefined;
 	const mcpManager = options.session.mcpManager ?? MCPManager.instance();
-	const { sessionFile, artifactsDir, contextFile } = await getArtifacts(options.session);
+	const { sessionFile, artifactsDir } = await getArtifacts(options.session);
 	const outputManager = getOutputManager(options.session);
 	const id = await outputManager.allocate(outputIdBase(parsed.label, agentName));
 	const assignment = parsed.prompt.trim();
-	const context = trimToUndefined(parsed.context);
 	// Suspend eval timeout accounting while the subagent owns control. The
 	// timeout clock restarts once the bridge returns to the cell runtime.
 	const result = await withBridgeTimeoutPause(options.emitStatus, () =>
@@ -259,7 +248,6 @@ export async function runEvalAgent(args: unknown, options: EvalAgentBridgeOption
 			agent: effectiveAgent,
 			task: renderSubagentPrompt(assignment),
 			assignment,
-			context,
 			description: trimToUndefined(parsed.label),
 			index: 0,
 			id,
@@ -271,7 +259,6 @@ export async function runEvalAgent(args: unknown, options: EvalAgentBridgeOption
 			sessionFile,
 			persistArtifacts: Boolean(sessionFile),
 			artifactsDir,
-			contextFile,
 			// Eval `agent()` subagents are short-lived programmatic helpers (data
 			// collection, structured output, parallel() fan-out). LSP server
 			// cold-start costs tens of seconds and is pure overhead here, so it is

package/src/eval/completion-bridge.ts

@@ -163,6 +163,7 @@ export async function runEvalCompletion(
 				apiKey: registry.resolver(model.provider, {
 					sessionId: options.session.getSessionId?.() ?? undefined,
 					baseUrl: model.baseUrl,
+					modelId: model.id,
 				}),
 				signal: options.signal,
 				reasoning: reasoningForTier(tier, model),

package/src/eval/js/shared/prelude.txt

@@ -65,7 +65,7 @@ if (!globalThis.__omp_js_prelude_loaded__) {
 	};
 
 	const agent = async (prompt, opts, ...rest) => {
-		const o = optionsArg("agent", opts, rest, "{ agentType, model, context, label, schema }");
+		const o = optionsArg("agent", opts, rest, "{ agentType, model, label, schema }");
 		const res = await globalThis.__omp_call_tool__("__agent__", { prompt, ...o });
 		const text = res && typeof res === "object" ? res.text : res;
 		return hasOwn(o, "schema") ? JSON.parse(text) : text;

package/src/eval/py/executor.ts

@@ -1,3 +1,4 @@
+import * as fs from "node:fs";
 import * as path from "node:path";
 
 import { getProjectDir, logger } from "@oh-my-pi/pi-utils";
@@ -15,6 +16,7 @@ import {
 	type KernelRuntimeEnv,
 	PythonKernel,
 } from "./kernel";
+import { resolveExplicitPythonRuntime } from "./runtime";
 import { ensurePyToolBridge, registerPyToolBridge } from "./tool-bridge";
 
 export type PythonKernelMode = "session" | "per-call";
@@ -42,6 +44,11 @@ export interface PythonExecutorOptions {
 	kernelOwnerId?: string;
 	/** Kernel mode (session reuse vs per-call) */
 	kernelMode?: PythonKernelMode;
+	/**
+	 * Explicit interpreter path (`python.interpreter` resolved from the
+	 * session's settings). Skips automatic runtime discovery when set.
+	 */
+	interpreter?: string;
 	/** Restart the kernel before executing */
 	reset?: boolean;
 	/** Session file path for accessing task outputs */
@@ -116,9 +123,9 @@ export interface PythonResult {
 // ---------------------------------------------------------------------------
 // Session bookkeeping
 //
-// One PythonKernel subprocess per (session id, cwd) tuple. The runner mutates
-// process-global cwd/sys.path during execution, so cross-directory work MUST
-// never share a live kernel. Multiple agent owners can still register against
+// One PythonKernel subprocess per (session id, cwd, interpreter) tuple. The
+// runner mutates process-global cwd/sys.path during execution, so cross-directory
+// work must never share a live kernel. Multiple agent owners can still register against
 // the same tuple; the kernel stays alive until the last owner detaches.
 // ---------------------------------------------------------------------------
 
@@ -139,8 +146,19 @@ function normalizeSessionCwd(cwd: string): string {
 	return path.resolve(cwd);
 }
 
-function buildSessionKey(sessionId: string, cwd: string): string {
-	return `${sessionId}\0${normalizeSessionCwd(cwd)}`;
+function normalizeExplicitInterpreter(cwd: string, interpreter: string | undefined): string {
+	if (interpreter === undefined) return "";
+	const resolved = resolveExplicitPythonRuntime(interpreter, cwd, {}).pythonPath;
+	try {
+		return fs.realpathSync.native(resolved);
+	} catch {
+		return resolved;
+	}
+}
+
+function buildSessionKey(sessionId: string, cwd: string, interpreter: string | undefined): string {
+	const normalizedCwd = normalizeSessionCwd(cwd);
+	return `${sessionId}\0${normalizedCwd}\0${normalizeExplicitInterpreter(normalizedCwd, interpreter)}`;
 }
 
 // ---------------------------------------------------------------------------
@@ -326,6 +344,7 @@ async function startKernel(cwd: string, options: PythonExecutorOptions): Promise
 		env: buildKernelEnv(options),
 		signal: options.signal,
 		deadlineMs: options.deadlineMs,
+		interpreter: options.interpreter,
 	});
 }
 
@@ -587,7 +606,10 @@ async function executeWithKernel(
 }
 
 async function ensureKernelAvailable(cwd: string, options: PythonExecutorOptions): Promise<void> {
-	const availability = await waitForPromiseWithCancellation(checkPythonKernelAvailability(cwd), options);
+	const availability = await waitForPromiseWithCancellation(
+		checkPythonKernelAvailability(cwd, options.interpreter),
+		options,
+	);
 	if (!availability.ok) {
 		throw new Error(availability.reason ?? "Python kernel unavailable");
 	}
@@ -618,7 +640,7 @@ async function executePerCall(code: string, cwd: string, options: PythonExecutor
 
 async function executeOnSession(code: string, cwd: string, options: PythonExecutorOptions): Promise<PythonResult> {
 	const sessionId = options.sessionId ?? `session:${cwd}`;
-	const sessionKey = buildSessionKey(sessionId, cwd);
+	const sessionKey = buildSessionKey(sessionId, cwd, options.interpreter);
 	if (options.bridge && !options.bridgeSessionId) {
 		options.bridgeSessionId = sessionId;
 	}

package/src/eval/py/index.ts

@@ -19,13 +19,17 @@ function readSetting<T>(session: ToolSession, key: string): T | undefined {
 	return settings?.get?.(key);
 }
 
+function readInterpreterSetting(session: ToolSession): string | undefined {
+	return readSetting<string>(session, "python.interpreter")?.trim() || undefined;
+}
+
 export default {
 	id: "python",
 	label: "Python",
 	highlightLang: "python",
 
 	async isAvailable(session: ToolSession): Promise<boolean> {
-		const availability = await checkPythonKernelAvailability(session.cwd);
+		const availability = await checkPythonKernelAvailability(session.cwd, readInterpreterSetting(session));
 		return availability.ok;
 	},
 
@@ -37,6 +41,7 @@ export default {
 			signal: opts.signal,
 			sessionId: namespaceSessionId(opts.sessionId),
 			kernelMode,
+			interpreter: readInterpreterSetting(opts.session),
 			sessionFile: opts.sessionFile,
 			artifactsDir: opts.session.getArtifactsDir?.() ?? undefined,
 			localRoots: resolveEvalUrlRoots(opts.session),