@sayknow-cli/coding-agent 0.3.15 → 0.4.0

package/src/tools/browser/tab-worker-entry.ts

@@ -3,19 +3,38 @@ import type { Transport, WorkerInbound, WorkerOutbound } from "./tab-protocol";
 import { WorkerCore } from "./tab-worker";
 
 if (!parentPort) throw new Error("tab-worker-entry: missing parentPort");
+const port = parentPort;
+port.once("message", bootstrap => {
+	if (!isBootstrap(bootstrap)) {
+		port.postMessage({ type: "bootstrap-failed", error: "Invalid tab worker bootstrap." });
+		port.close();
+		return;
+	}
 
-const transport: Transport = {
-	send(msg, transferList) {
-		parentPort!.postMessage(msg, transferList ?? []);
-	},
-	onMessage(handler) {
-		const wrap = (message: unknown): void => handler(message as WorkerOutbound | WorkerInbound);
-		parentPort!.on("message", wrap);
-		return () => parentPort!.off("message", wrap);
-	},
-	close() {
-		parentPort!.close();
-	},
-};
+	const transport: Transport = {
+		send(msg, transferList) {
+			port.postMessage(msg, transferList ?? []);
+		},
+		onMessage(handler) {
+			const wrap = (message: unknown): void => handler(message as WorkerOutbound | WorkerInbound);
+			port.on("message", wrap);
+			return () => port.off("message", wrap);
+		},
+		close() {
+			port.close();
+		},
+	};
 
-new WorkerCore(transport);
+	new WorkerCore(transport);
+	port.postMessage({ type: "bootstrap-ready", version: 1, mode: "native-free" });
+});
+
+function isBootstrap(message: unknown): message is Extract<WorkerInbound, { type: "bootstrap" }> {
+	return (
+		typeof message === "object" &&
+		message !== null &&
+		(message as { type?: unknown }).type === "bootstrap" &&
+		(message as { version?: unknown }).version === 1 &&
+		(message as { mode?: unknown }).mode === "native-free"
+	);
+}

package/src/tools/browser/tab-worker-path-resolver.ts

@@ -0,0 +1,67 @@
+import * as os from "node:os";
+import * as path from "node:path";
+import * as url from "node:url";
+
+const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
+const TOP_LEVEL_INTERNAL_URL_PREFIXES = ["agent://", "artifact://", "rule://", "local://"] as const;
+
+function normalizeAtPrefix(filePath: string): string {
+	if (!filePath.startsWith("@")) return filePath;
+
+	const withoutAt = filePath.slice(1);
+	if (
+		withoutAt.startsWith("/") ||
+		withoutAt === "~" ||
+		withoutAt.startsWith("~/") ||
+		path.win32.isAbsolute(withoutAt) ||
+		withoutAt.startsWith("agent://") ||
+		withoutAt.startsWith("artifact://") ||
+		withoutAt.startsWith("rule://") ||
+		withoutAt.startsWith("local:")
+	) {
+		return withoutAt;
+	}
+
+	return filePath;
+}
+
+function expandPath(filePath: string): string {
+	const normalized = normalizeAtPrefix(filePath).replace(UNICODE_SPACES, " ");
+	if (normalized.toLowerCase().startsWith("file://")) {
+		try {
+			return expandTilde(url.fileURLToPath(normalized));
+		} catch {
+			return normalized;
+		}
+	}
+	return expandTilde(normalized);
+}
+
+function expandTilde(filePath: string): string {
+	const home = os.homedir();
+	if (filePath === "~") return home;
+	if (filePath.startsWith("~/") || filePath.startsWith("~\\")) return home + filePath.slice(1);
+	if (filePath.startsWith("~")) return path.join(home, filePath.slice(1));
+	return filePath;
+}
+
+function normalizeLocalScheme(filePath: string): string {
+	return filePath.replace(/^(local:)\/(?!\/)/, "$1//");
+}
+
+/** Resolve filesystem-only worker inputs without evaluating the broad path utility module. */
+export function resolveTabWorkerPath(filePath: string, cwd: string): string {
+	const normalized = normalizeLocalScheme(filePath);
+	const expanded = expandPath(normalized);
+	const expandedAndNormalized = normalizeLocalScheme(expanded);
+	for (const prefix of TOP_LEVEL_INTERNAL_URL_PREFIXES) {
+		if (expandedAndNormalized.startsWith(prefix)) {
+			throw new Error(
+				`Path "${normalized}" uses internal scheme "${prefix}" and must be resolved through the proper protocol handler, not as a filesystem path.`,
+			);
+		}
+	}
+
+	if (/^\/+$/u.test(expanded)) return cwd;
+	return path.isAbsolute(expanded) ? expanded : path.resolve(cwd, expanded);
+}

package/src/tools/browser/tab-worker-smoke.ts

@@ -0,0 +1,87 @@
+import { isCompiledBinary } from "@sayknow-cli/utils/env";
+import type { WorkerInbound, WorkerOutbound } from "./tab-protocol";
+
+interface SmokeWorkerHandle {
+	postMessage(message: WorkerInbound): void;
+	addEventListener(type: string, listener: EventListener): void;
+	removeEventListener(type: string, listener: EventListener): void;
+	terminate(): void;
+}
+
+const SMOKE_TIMEOUT_MS = 5_000;
+const TAB_WORKER_MODE = "native-free";
+
+function smokeStartupError(stage: string): Error {
+	return new Error(
+		`Tab worker startup failed (stage=${stage}, mode=${TAB_WORKER_MODE}, platform=${process.platform}).`,
+	);
+}
+
+/**
+ * Starts the real tab worker entry without connecting to a browser, then proves
+ * its bootstrap and shutdown protocol. The compiled branch deliberately keeps
+ * a static literal for Bun's --compile worker discovery.
+ */
+export async function smokeTestTabWorker(timeoutMs = SMOKE_TIMEOUT_MS): Promise<void> {
+	const worker = isCompiledBinary()
+		? new Worker("./packages/coding-agent/src/tools/browser/tab-worker-entry.ts", { type: "module" })
+		: new Worker(new URL("./tab-worker-entry.ts", import.meta.url).href, { type: "module" });
+	await smokeTestTabWorkerWithWorkerForTest(worker, timeoutMs);
+}
+
+/** Test-only: verify the smoke handshake against a controlled worker transport. */
+export async function smokeTestTabWorkerWithWorkerForTest(worker: SmokeWorkerHandle, timeoutMs: number): Promise<void> {
+	type SmokePhase = "await-bootstrap" | "await-closed";
+	let phase: SmokePhase = "await-bootstrap";
+	const { promise, resolve, reject } = Promise.withResolvers<void>();
+	let settled = false;
+	let timeout: NodeJS.Timeout | undefined;
+
+	const cleanup = (): void => {
+		if (timeout) clearTimeout(timeout);
+		worker.removeEventListener("message", onMessage);
+		worker.removeEventListener("error", onError);
+		worker.removeEventListener("messageerror", onMessageError);
+	};
+	const succeed = (): void => {
+		if (settled) return;
+		settled = true;
+		resolve();
+	};
+	const fail = (stage: string): void => {
+		if (settled) return;
+		settled = true;
+		reject(smokeStartupError(stage));
+	};
+	const onMessage: EventListener = event => {
+		const message = (event as MessageEvent<WorkerOutbound>).data;
+		if (message.type === "log") return;
+		if (phase === "await-bootstrap") {
+			if (message.type === "bootstrap-ready" && message.version === 1 && message.mode === TAB_WORKER_MODE) {
+				phase = "await-closed";
+				worker.postMessage({ type: "close" } satisfies WorkerInbound);
+			} else if (message.type === "bootstrap-failed") {
+				fail("bootstrap");
+			} else {
+				fail("protocol-phase");
+			}
+			return;
+		}
+		if (message.type === "closed") succeed();
+		else fail("protocol-phase");
+	};
+	const onError: EventListener = () => fail("error");
+	const onMessageError: EventListener = () => fail("messageerror");
+
+	worker.addEventListener("message", onMessage);
+	worker.addEventListener("error", onError);
+	worker.addEventListener("messageerror", onMessageError);
+	timeout = setTimeout(() => fail("smoke-timeout"), timeoutMs);
+	try {
+		worker.postMessage({ type: "bootstrap", version: 1, mode: TAB_WORKER_MODE } satisfies WorkerInbound);
+		await promise;
+	} finally {
+		cleanup();
+		worker.terminate();
+	}
+}

package/src/tools/browser/tab-worker.ts

@@ -2,7 +2,8 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 
-import { Snowflake, untilAborted } from "@sayknow-cli/utils";
+import { untilAborted } from "@sayknow-cli/utils/abortable";
+import { Snowflake } from "@sayknow-cli/utils/snowflake";
 import type { HTMLElement } from "linkedom";
 import type {
 	Browser,
@@ -17,8 +18,6 @@ import type {
 import { JsRuntime, type RuntimeHooks } from "../../eval/js/shared/runtime";
 import type { JsDisplayOutput } from "../../eval/js/shared/types";
 import { resizeImage } from "../../utils/image-resize";
-import { resolveToCwd } from "../path-utils";
-import { formatScreenshot } from "../render-utils";
 import { ToolAbortError, ToolError, throwIfAborted } from "../tool-errors";
 import {
 	applyStealthPatches,
@@ -28,6 +27,7 @@ import {
 	loadPuppeteerInWorker,
 } from "./launch";
 import { extractReadableFromHtml, type ReadableFormat, type ReadableResult } from "./readable";
+import { formatScreenshot } from "./screenshot-format";
 import type {
 	Observation,
 	ObservationEntry,
@@ -41,6 +41,7 @@ import type {
 	WorkerInbound,
 	WorkerInitPayload,
 } from "./tab-protocol";
+import { resolveTabWorkerPath } from "./tab-worker-path-resolver";
 
 declare global {
 	interface Element extends HTMLElement {}
@@ -454,7 +455,7 @@ export class WorkerCore {
 			});
 			if (payload.mode === "headless") {
 				this.#page = await this.#browser.newPage();
-				await applyStealthPatches(this.#browser, this.#page, { browserSession: null, override: null });
+				await applyStealthPatches(this.#browser, this.#page, { browserSession: null, override: null }, payload.geo);
 				await applyViewport(this.#page, payload.viewport);
 				if (payload.dialogs) this.#applyDialogPolicy(payload.dialogs);
 				if (payload.url) {
@@ -813,7 +814,8 @@ export class WorkerCore {
 			{ type: "image", data: buffer.toBase64(), mimeType: "image/png" },
 			{ maxWidth: 1024, maxHeight: 1024, maxBytes: 150 * 1024, jpegQuality: 70 },
 		);
-		const explicitPath = opts.save ? resolveToCwd(opts.save, session.cwd) : undefined;
+		const explicitPath = opts.save ? resolveTabWorkerPath(opts.save, session.cwd) : undefined;
+
 		const dest =
 			explicitPath ??
 			(session.browserScreenshotDir
@@ -950,7 +952,7 @@ export class WorkerCore {
 			page.locator(normalizeSelector(selector)).setTimeout(timeoutMs).waitHandle(),
 		)) as ElementHandle;
 		try {
-			const absolute = filePaths.map(filePath => resolveToCwd(filePath, session.cwd));
+			const absolute = filePaths.map(filePath => resolveTabWorkerPath(filePath, session.cwd));
 			const upload = handle as unknown as { uploadFile: (...paths: string[]) => Promise<void> };
 			const tagName = (await untilAborted(signal, () =>
 				handle.evaluate(el => (el as unknown as { tagName: string }).tagName),

package/src/tools/browser.ts

@@ -233,6 +233,12 @@ export class BrowserTool implements AgentTool<typeof browserSchema, BrowserToolD
 						}
 					: undefined,
 				appArgs: params.app?.args,
+				profileReuse:
+					(this.session.settings.get("browser.profileReuse") as "auto" | "opt-in" | undefined) ?? "auto",
+				geo: {
+					timezone: this.session.settings.get("browser.geo.timezone") as string | undefined,
+					locale: this.session.settings.get("browser.geo.locale") as string | undefined,
+				},
 				signal,
 			}),
 		);

package/src/tools/computer.ts

@@ -6,7 +6,7 @@ import type { ImageContent } from "@sayknow-cli/ai";
 import { prompt } from "@sayknow-cli/utils";
 import * as z from "zod/v4";
 import computerDescription from "../prompts/tools/computer.md" with { type: "text" };
-import { resizeImage } from "../utils/image-resize";
+import { formatDimensionNote, resizeImage } from "../utils/image-resize";
 import { markScreenshotFallbackDirCreatedForGc } from "./computer-gc";
 import type { ToolSession } from "./index";
 import type { OutputMeta } from "./output-meta";
@@ -701,11 +701,16 @@ async function inlineImageContentFromNativeResult(
 	details: ComputerToolDetails,
 	session: ToolSession,
 ): Promise<ImageContent | undefined> {
+	// Anthropic rejects requests carrying more than 20 images when any image
+	// exceeds 2000px per dimension ("many-image requests"), so gating on bytes
+	// alone is not enough: an in-budget full-resolution capture can still brick
+	// the session once enough screenshots accumulate in history. Always route
+	// through resizeImage (its fast path returns already-small images
+	// untouched) and tell the model how to map coordinates back to the native
+	// screenshot frame when the inline image was scaled.
 	const image = fullResolutionImageContentFromNativeResult(value);
 	if (!image) return undefined;
 	const maxBytes = getInlineScreenshotMaxBytes(session);
-	const originalBytes = Buffer.byteLength(image.data, "base64");
-	if (originalBytes <= maxBytes) return image;
 
 	try {
 		const resized = await resizeImage(image, {
@@ -715,6 +720,8 @@ async function inlineImageContentFromNativeResult(
 			jpegQuality: COMPUTER_INLINE_SCREENSHOT_JPEG_QUALITY,
 		});
 		if (resized.buffer.length <= maxBytes) {
+			const note = formatDimensionNote(resized);
+			if (note) details.message = `${details.message} ${note}`;
 			return { type: "image", data: resized.data, mimeType: resized.mimeType };
 		}
 	} catch {

package/src/tools/cron.ts

@@ -58,6 +58,8 @@ export interface CronJobSnapshot {
 	createdAt: number;
 	expiresAt?: number;
 	nextFireAt?: number;
+	/** True while this owner-scoped schedule's delivery is in progress. */
+	firing?: boolean;
 	humanSchedule: string;
 	ownerId?: string;
 }
@@ -444,7 +446,7 @@ function formatCronFireContent(snapshot: CronJobSnapshot): string {
 	return `<task-notification>\nScheduled task ${snapshot.id} fired (${snapshot.humanSchedule}).\n\n${snapshot.prompt}\n</task-notification>`;
 }
 
-function deliverCronFire(record: CronScheduleRecord): void {
+function deliverCronFire(record: CronScheduleRecord): Promise<void> | undefined {
 	const content = formatCronFireContent(record.snapshot);
 	const details = {
 		id: record.snapshot.id,
@@ -455,16 +457,9 @@ function deliverCronFire(record: CronScheduleRecord): void {
 		{ customType: "cron-fire", content, display: false, attribution: "agent", details },
 		{ triggerTurn: true, deliverAs: "followUp" },
 	);
-	if (sendPromise) {
-		void sendPromise.catch(error => {
-			logger.warn("Cron fire delivery failed", {
-				id: record.snapshot.id,
-				error: error instanceof Error ? error.message : String(error),
-			});
-		});
-		return;
-	}
+	if (sendPromise) return sendPromise;
 	record.session.steer?.({ customType: "cron-fire", content, details });
+	return undefined;
 }
 
 function scheduleRecord(ownerId: string | undefined, state: OwnerScheduleState, record: CronScheduleRecord): void {
@@ -509,16 +504,35 @@ function fireRecord(ownerId: string | undefined, state: OwnerScheduleState, id:
 		deleteRecord(ownerId, id);
 		return;
 	}
+	record.snapshot.firing = true;
+	notifyCronChange();
+	const settle = () => {
+		if (record.disposed) return;
+		record.snapshot.firing = false;
+		notifyCronChange();
+		if (!record.snapshot.recurring) {
+			deleteRecord(ownerId, id);
+			return;
+		}
+		scheduleRecord(ownerId, state, record);
+	};
 	try {
-		deliverCronFire(record);
+		const delivery = deliverCronFire(record);
+		if (delivery) {
+			void delivery.then(settle, error => {
+				logger.warn("Cron fire delivery failed", {
+					id,
+					error: error instanceof Error ? error.message : String(error),
+				});
+				settle();
+			});
+		} else {
+			settle();
+		}
 	} catch (error) {
 		logger.warn("Cron fire delivery failed", { id, error: error instanceof Error ? error.message : String(error) });
+		settle();
 	}
-	if (!record.snapshot.recurring) {
-		deleteRecord(ownerId, id);
-		return;
-	}
-	scheduleRecord(ownerId, state, record);
 }
 
 const CRON_ID_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";

package/src/tools/fetch.ts

@@ -1292,20 +1292,20 @@ async function materializeReadUrlCacheEntry(
 	session: ToolSession,
 	entry: ReadUrlCacheEntry,
 ): Promise<ReadUrlCacheEntry | null> {
+	if (entry.output.length > 0) return entry;
 	if (entry.artifactId) {
 		const artifactOutput = await readArtifactOutput(session, entry.artifactId);
 		if (artifactOutput !== null) {
 			return { ...entry, output: artifactOutput };
 		}
 	}
-
-	return entry.output.length > 0 ? entry : null;
+	return null;
 }
 
 async function persistReadUrlArtifact(session: ToolSession, output: string): Promise<string | undefined> {
 	const { path: artifactPath, id } = (await session.allocateOutputArtifact?.("read")) ?? {};
 	if (!artifactPath) return undefined;
-	await Bun.write(artifactPath, output);
+	await Bun.write(artifactPath, wrapUntrustedContent(output));
 	return id;
 }
 
@@ -1379,6 +1379,13 @@ export async function loadReadUrlCacheEntry(
 	return fresh;
 }
 
+const UNTRUSTED_CONTENT_OPEN = "<untrusted-content>";
+const UNTRUSTED_CONTENT_CLOSE = "</untrusted-content>";
+
+export function wrapUntrustedContent(content: string): string {
+	return `${UNTRUSTED_CONTENT_OPEN}\n${content.replace(/<\/untrusted-content>/gi, "&lt;/untrusted-content>")}\n${UNTRUSTED_CONTENT_CLOSE}`;
+}
+
 function buildUrlReadOutput(result: FetchRenderResult, content: string): string {
 	let output = "";
 	output += `URL: ${result.finalUrl}\n`;
@@ -1413,7 +1420,7 @@ export async function executeReadUrl(
 		truncated: Boolean(cacheEntry.details.truncated || needsArtifact),
 	};
 
-	const contentBlocks: Array<TextContent | ImageContent> = [{ type: "text", text: output }];
+	const contentBlocks: Array<TextContent | ImageContent> = [{ type: "text", text: wrapUntrustedContent(output) }];
 	if (cacheEntry.image) {
 		contentBlocks.push({ type: "image", data: cacheEntry.image.data, mimeType: cacheEntry.image.mimeType });
 	}

package/src/tools/index.ts

@@ -1,16 +1,17 @@
 import type { AgentTelemetryConfig, AgentTool } from "@sayknow-cli/agent-core";
 import type { Model, ServiceTier, ToolChoice } from "@sayknow-cli/ai";
-import { $env, $flag, logger } from "@sayknow-cli/utils";
+import { $env, logger } from "@sayknow-cli/utils";
 import type { PromptTemplate } from "../config/prompt-templates";
 import type { Settings } from "../config/settings";
 import { EditTool } from "../edit";
+import { isTruthyPythonFlag } from "../eval/py/env";
 import { checkPythonKernelAvailability } from "../eval/py/kernel";
 import type { Skill } from "../extensibility/skills";
 import type { GoalModeState, GoalRuntime } from "../goals";
 import { GoalTool } from "../goals/tools/goal-tool";
 import type { HindsightSessionState } from "../hindsight/state";
 import { LspTool } from "../lsp";
-import type { WorkflowGateEmitter } from "../modes/shared/agent-wire/unattended-session";
+import type { WorkflowGateEmitter } from "../modes/shared/agent-wire/workflow-gate-broker";
 import type { PlanModeState } from "../plan-mode/state";
 import type { AgentRegistry } from "../registry/agent-registry";
 import type {
@@ -114,7 +115,6 @@ export type ContextFileEntry = {
 	depth?: number;
 };
 
-export type { DiscoverableMCPTool } from "../runtime-mcp/discoverable-tool-metadata";
 export type {
 	DiscoverableTool,
 	DiscoverableToolSearchIndex,
@@ -200,9 +200,10 @@ export interface AskRemoteReceipt {
 export type AskAnswerSourceResult = AskRemoteReceipt | string | undefined;
 
 /**
- * Source of remote answers. `awaitAnswer` remains the legacy wire for existing
- * integrations; typed sources opt into `awaitAnswerRequest`. This keeps an old
- * string-only source from accidentally acquiring acknowledgement authority.
+ * Source of remote answers for interactive asks. `awaitAnswer` remains the legacy
+ * wire for existing integrations; typed sources opt into `awaitAnswerRequest`.
+ * This keeps a string-only source from accidentally acquiring acknowledgement
+ * authority while allowing SDK-routed interactions to settle durably.
  */
 export interface AskAnswerSource {
 	awaitAnswer(question: string, options: string[], signal?: AbortSignal): Promise<string | undefined>;
@@ -215,6 +216,8 @@ export interface ToolSession {
 	cwd: string;
 	/** Whether UI is available */
 	hasUI: boolean;
+	/** Whether this session will bind a workflow-gate emitter after tool construction. */
+	workflowGateEligible?: boolean;
 	/** Skip Python kernel availability check and warmup */
 	skipPythonPreflight?: boolean;
 	/** Pre-loaded context files (AGENTS.md, etc) */
@@ -261,6 +264,8 @@ export interface ToolSession {
 	requestForegroundBashBackground?: () => boolean;
 	/** Get session ID */
 	getSessionId?: () => string | null;
+	/** Whether local:// must use external managed scratch instead of artifacts/local. */
+	isManagedSessionDestination?: () => boolean;
 	/** Get Hindsight runtime state for this agent session. */
 	getHindsightSessionState?: () => HindsightSessionState | undefined;
 	/** Agent identity used for IRC routing. Returns the registry id (e.g. "0-Main", "0-AuthLoader"). */
@@ -277,6 +282,8 @@ export interface ToolSession {
 	bashRestrictionProfile?: BashRestrictionProfile;
 	/** Optional per-session allowlist for tools exposed through search_tool_bm25. */
 	discoverableToolAllowedNames?: readonly string[];
+	/** Throw instead of warn when toolNames contains an unknown name. */
+	strictToolNames?: boolean;
 	/** Get artifacts directory for artifact:// URLs */
 	getArtifactsDir?: () => string | null;
 	/** Get the ArtifactManager backing this session (shared across parent + subagents). */
@@ -305,12 +312,11 @@ export interface ToolSession {
 	getPlanModeState?: () => PlanModeState | undefined;
 	/** Goal mode state (if active or paused) */
 	getGoalModeState?: () => GoalModeState | undefined;
-	/** Unattended workflow-gate emitter (present only when unattended mode is negotiated). */
+	/** SDK workflow-gate emitter, when a remote gate responder is connected. */
 	getWorkflowGateEmitter?: () => WorkflowGateEmitter | undefined;
 	/**
-	 * Optional remote answer source for interactive asks. When present, the ask
-	 * tool races the local UI selection against a remote answer (e.g. a Telegram
-	 * reply via the notifications SDK) so asks can be answered without RPC mode.
+	 * Optional SDK-routed answer source for interactive asks. When present, the
+	 * tool races the local UI selection against the remote SDK answer.
 	 * No-op when undefined: the ask path behaves exactly as before.
 	 */
 	getAskAnswerSource?: () => AskAnswerSource | undefined;
@@ -326,18 +332,6 @@ export interface ToolSession {
 	getTodoPhases?: () => TodoPhase[];
 	/** Replace cached todo phases for this session. */
 	setTodoPhases?: (phases: TodoPhase[]) => void;
-	/** Whether MCP tool discovery is active for this session. */
-	isMCPDiscoveryEnabled?: () => boolean;
-	/** Get hidden-but-discoverable MCP tools for search_tool_bm25 prompts and fallbacks.
-	 * @deprecated Use getDiscoverableTools with source filter instead. */
-	getDiscoverableMCPTools?: () => import("../runtime-mcp/discoverable-tool-metadata").DiscoverableMCPTool[];
-	/** Get the cached discoverable MCP search index for search_tool_bm25 execution.
-	 * @deprecated Use getDiscoverableToolSearchIndex instead. */
-	getDiscoverableMCPSearchIndex?: () => import("../tool-discovery/tool-index").DiscoverableMCPSearchIndex;
-	/** Get MCP tools activated by prior search_tool_bm25 calls. */
-	getSelectedMCPToolNames?: () => string[];
-	/** Merge MCP tool selections into the active session tool set. */
-	activateDiscoveredMCPTools?: (toolNames: string[]) => Promise<string[]>;
 	// ── Generic tool discovery (unified — covers built-in + MCP + extension) ──
 	/** Whether any form of tool discovery is active (tools.discoveryMode !== "off" or mcp.discoveryMode). */
 	isToolDiscoveryEnabled?: () => boolean;
@@ -511,20 +505,67 @@ export interface EvalBackendsAllowance {
 }
 
 /**
- * Parse PI_PY / PI_JS environment variables. Each is a boolean flag; unset
- * means "not specified, defer to settings". Returns null when neither is set
+ * Parse the `SKC_PY` multi-value token into per-backend booleans.
+ *
+ * Tokens (case-insensitive):
+ * - `0` / `bash` → JavaScript only (`{ py: false, js: true }`)
+ * - `1` / `py`   → Python only (`{ py: true, js: false }`)
+ * - `js`         → JavaScript only (`{ py: false, js: true }`)
+ * - `mix` / `both` → both backends (`{ py: true, js: true }`)
+ *
+ * Returns `null` when `SKC_PY` is unset, empty, or holds an unrecognized
+ * token, so the caller can fall back to the legacy `PI_PY` / `PI_JS` flags or
+ * per-key settings. This matches the documented contract that invalid values
+ * are ignored.
+ */
+export function parseSkcPy(env: Record<string, string | undefined>): { py: boolean; js: boolean } | null {
+	const raw = env.SKC_PY;
+	if (raw === undefined) return null;
+	const token = raw.trim().toLowerCase();
+	if (token === "") return null;
+	switch (token) {
+		case "0":
+		case "bash":
+			return { py: false, js: true };
+		case "1":
+		case "py":
+			return { py: true, js: false };
+		case "js":
+			return { py: false, js: true };
+		case "mix":
+		case "both":
+			return { py: true, js: true };
+		default:
+			return null;
+	}
+}
+
+/**
+ * Parse legacy `PI_PY` / `PI_JS` boolean flags. Each is a boolean flag; unset
+ * means "not specified, defer to settings". Returns `null` when neither is set
  * so the caller can fall through to `readEvalBackendsAllowance` per key.
  */
-function getEvalBackendsFromEnv(): EvalBackendsAllowance | null {
-	const pyEnv = $env.PI_PY;
-	const jsEnv = $env.PI_JS;
+function parseLegacyEvalEnvFlags(env: Record<string, string | undefined>): EvalBackendsAllowance | null {
+	const pyEnv = env.PI_PY;
+	const jsEnv = env.PI_JS;
 	if (pyEnv === undefined && jsEnv === undefined) return null;
 	return {
-		python: pyEnv === undefined ? true : $flag("PI_PY"),
-		js: jsEnv === undefined ? true : $flag("PI_JS"),
+		python: pyEnv === undefined ? true : isTruthyPythonFlag(pyEnv),
+		js: jsEnv === undefined ? true : isTruthyPythonFlag(jsEnv),
 	};
 }
 
+/**
+ * Resolve eval-backend allowance from environment only. `SKC_PY` wins when set
+ * to a recognized token; otherwise the legacy `PI_PY` / `PI_JS` flags apply.
+ * Returns `null` when no env override is set so the caller can defer to settings.
+ */
+export function resolveEvalBackendsFromEnv(env: Record<string, string | undefined>): EvalBackendsAllowance | null {
+	const skc = parseSkcPy(env);
+	if (skc) return { python: skc.py, js: skc.js };
+	return parseLegacyEvalEnvFlags(env);
+}
+
 /** Read per-backend allowance from settings (defaults true). */
 export function readEvalBackendsAllowance(session: ToolSession): EvalBackendsAllowance {
 	return {
@@ -534,13 +575,20 @@ export function readEvalBackendsAllowance(session: ToolSession): EvalBackendsAll
 }
 
 /**
- * Materialize the active eval backend allowance: PI_PY / PI_JS env flags
- * override the per-key settings; otherwise settings (defaults true) win.
+ * Materialize the active eval backend allowance. `SKC_PY` takes precedence
+ * over the legacy `PI_PY` / `PI_JS` env flags, which in turn override the
+ * per-key settings (defaults true). When no env override is set, settings win.
  */
 export function resolveEvalBackends(session: ToolSession): EvalBackendsAllowance {
-	return getEvalBackendsFromEnv() ?? readEvalBackendsAllowance(session);
+	return resolveEvalBackendsFromEnv($env) ?? readEvalBackendsAllowance(session);
 }
 
+export {
+	resolvePythonIntegrationGate,
+	resolvePythonIpcTrace,
+	resolvePythonSkipCheck,
+} from "../eval/py/env";
+
 /**
  * Create tools from BUILTIN_TOOLS registry.
  */
@@ -670,6 +718,14 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 		requestedTools.push("yield");
 	}
 
+	if (requestedTools) {
+		const unknownToolNames = requestedTools.filter(name => !allToolsByRequestName.has(name));
+		if (unknownToolNames.length > 0) {
+			const message = `Unknown tool name${unknownToolNames.length === 1 ? "" : "s"}: ${unknownToolNames.join(", ")}`;
+			if (session.strictToolNames) throw new Error(message);
+			logger.warn(message);
+		}
+	}
 	const filteredRequestedTools = requestedTools
 		?.map(name => allToolsByRequestName.get(name))
 		.filter((entry): entry is [string, ToolFactory] => entry !== undefined)