@code-yeongyu/senpi-codemode 2026.10.8 → 2026.10.10-10

package/src/kernels/shared/subprocess-process.ts

@@ -151,6 +151,11 @@ export class SubprocessProcess {
 	}
 
 	private kill(signal: NodeJS.Signals): void {
+		if (globalThis.process.platform === "win32") {
+			if (this.child.pid !== undefined) killProcessTree(this.child.pid);
+			else this.child.kill(signal);
+			return;
+		}
 		if (this.child.pid !== undefined) {
 			try {
 				globalThis.process.kill(-this.child.pid, signal);
@@ -163,6 +168,15 @@ export class SubprocessProcess {
 	}
 }
 
+// Windows has no process-group signal: taskkill /T /F walks the tree rooted at the child.
+function killProcessTree(pid: number): void {
+	try {
+		nodeSpawn("taskkill", ["/PID", String(pid), "/T", "/F"], { stdio: "ignore" });
+	} catch (error) {
+		if (!(error instanceof Error)) throw error;
+	}
+}
+
 export function spawnSubprocess(spawn: SubprocessSpawn | undefined, request: SubprocessSpawnRequest): SubprocessLike {
 	if (spawn) return spawn(request.command, request.args, { cwd: request.cwd, env: request.env });
 	const child = nodeSpawn(request.command, [...request.args], {

package/src/prompt/eval-prompt.ts

@@ -18,6 +18,8 @@ export interface EvalPromptParts {
 
 export interface EvalPromptOptions {
 	readonly spawns: boolean;
+	/** `prompt.advertiseHelpers`: true appends one pointer line to the helper documentation entry. */
+	readonly advertiseHelpers?: boolean;
 	/** Whether the session registry exposes the monitor tool through eval. */
 	readonly monitor?: boolean;
 	readonly spawnDefaultAgent?: string;
@@ -74,6 +76,10 @@ export function evalEmphasisStyle(modelId: string | undefined): EvalEmphasisStyl
 type ContextValue = string | boolean;
 type Context = Readonly<Record<string, ContextValue>>;
 
+/** The single line `prompt.advertiseHelpers: true` adds; off by default, so the default description is unchanged. */
+export const ADVERTISED_HELPERS_LINE =
+	"Advanced cell helpers (handle controls, wait(), kernel tools in workpools) are documented on demand: tool_schema('eval:helpers').";
+
 export function buildEvalPrompt(
 	enabled: EnabledLanguages,
 	options: EvalPromptOptions = { spawns: false },
@@ -104,9 +110,10 @@ export function buildEvalPrompt(
 		maxDetachedCells: String(options.maxDetachedCells ?? DEFAULT_MAX_DETACHED_CELLS),
 		kernelPreludeDocs: (options.kernelPreludes ?? []).map((prelude) => prelude.documentation).join("\n"),
 	};
-	const description = renderTemplate(EVAL_PROMPT_TEMPLATE, context)
+	const rendered = renderTemplate(EVAL_PROMPT_TEMPLATE, context)
 		.replace(/\n{3,}/g, "\n\n")
 		.trim();
+	const description = options.advertiseHelpers === true ? `${rendered}\n\n${ADVERTISED_HELPERS_LINE}` : rendered;
 	return {
 		description,
 		promptSnippet: "Run one incremental code cell in a persistent language kernel.",

package/src/tool/AGENTS.md

@@ -17,6 +17,7 @@ anchor most suites).
 | Code preview layout | `code-preview.ts` -> `display-code.ts` (JS: `display-js*.ts` Bun-only masked `Bun.Transpiler`; Python: `display-python*.ts` user interpreter, background + repaint) |
 | Status events, execution events | `status-events.ts`, `eval-execution-event.ts` |
 | Interrupt, capture | `interrupt-note.ts`, `call-capture.ts` |
+| Magic cells | `magic-cells.ts` (parsing), `magic-cell-host.ts` (`%pip`, `%bun`/`%npm`, `%environment`), `load-cell.ts` (`%load`); installs live in `../environments/` |
 
 ## CONVENTIONS
 

package/src/tool/cell-handler.ts

@@ -14,6 +14,7 @@ import { appendSchemaHint } from "../bridges/schema-hint.ts";
 import type { CompletionRequest, CompletionResult } from "../completion/handler.ts";
 import { handleCompletionToolCall } from "../completion/tool-bridge.ts";
 import type { ResolvedCodemodeSettings } from "../config/settings.ts";
+import type { PackagesInstallEnvironments } from "../environments/packages-install.ts";
 import type { HandleRegistry } from "../handles/handle-registry.ts";
 import type { KernelToolsCapability } from "../kernels/js/kernel-tools-types.ts";
 import {
@@ -48,12 +49,14 @@ export interface CellBridgeRuntime {
 	readonly ctx: ExtensionContext;
 	readonly artifactPath?: string;
 	readonly imageResizer?: EvalImageResizer;
-	/** This cell's live kernel-tool capability; only a JS kernel has one (#1754). */
+	/** This cell's live kernel-tool capability; JS and Python kernels have one (#1754, #2731). */
 	readonly kernelTools?: KernelToolsCapability;
 	/** The session generation's handle registry behind `wait()` / `handle()` / completion handles. */
 	readonly handles?: HandleRegistry;
 	/** Absolute wall-clock deadline of this cell; a completion handle it creates is bounded by it. */
 	readonly hardDeadlineMs?: number;
+	/** A JS cell's session environment for `packages.install()`; Python cells reach theirs over the bridge. */
+	readonly environments?: PackagesInstallEnvironments;
 }
 
 export class CellHandler {
@@ -235,22 +238,20 @@ export class CellHandler {
 			this.#kernel.deliverToolReply({ type: "tool-reply", callId: message.callId, ok: true, value: reply.value });
 		} catch (error) {
 			if (!this.#state.active) return;
-			const text = appendSchemaHint(
-				error instanceof Error ? error.message : String(error),
-				message.toolName,
-				this.#toolParameters(message.toolName),
-			);
+			const code =
+				error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : undefined;
+			const errorMessage = error instanceof Error ? error.message : String(error);
+			// A blocked call (a permission denial or another hook's veto) is not an argument problem.
+			const text =
+				code === "blocked"
+					? errorMessage
+					: appendSchemaHint(errorMessage, message.toolName, this.#toolParameters(message.toolName));
 			recordToolCall(this.#state.toolCalls, false, capture, undefined, text);
 			this.#kernel.deliverToolReply({
 				type: "tool-reply",
 				callId: message.callId,
 				ok: false,
-				error: {
-					message: text,
-					...(error instanceof Error && "code" in error && typeof error.code === "string"
-						? { code: error.code }
-						: {}),
-				},
+				error: { message: text, ...(code === undefined ? {} : { code }) },
 			});
 		}
 		this.#resultBuilder.emitUpdate(false);

package/src/tool/cell-reserved-dispatch.ts

@@ -29,6 +29,7 @@ export function reservedDispatchContext(
 		marshalToolResult,
 		...(runtime.handles === undefined ? {} : { handles: runtime.handles }),
 		...(host === undefined ? {} : { evalHandleHost: host }),
+		...(runtime.environments === undefined ? {} : { environments: runtime.environments }),
 	};
 }
 

package/src/tool/cell-runtime.ts

@@ -219,8 +219,10 @@ export class CellResultBuilder {
 	}
 
 	#liveUpdateText(): string {
-		if (this.#state.status === "queued" && this.#state.queuedBehind?.length) {
-			return `queued behind ${this.#state.queuedBehind.join(", ")} in the ${this.#state.input.language} kernel`;
+		if (this.#state.status === "queued" && this.#state.queuedBehind !== undefined) {
+			return this.#state.queuedBehind.length === 0
+				? `waiting for the ${this.#state.input.language} kernel to be ready`
+				: `queued behind ${this.#state.queuedBehind.join(", ")} in the ${this.#state.input.language} kernel`;
 		}
 		const summary = this.#state.input.summary === undefined ? "" : ` ${this.#state.input.summary}`;
 		const output = this.#liveLines.text();

package/src/tool/detached-cell-contract.ts

@@ -1,5 +1,6 @@
 import type { AgentToolResult } from "@code-yeongyu/senpi";
 import type { WakeSourceState } from "../extension/wake-source-state.ts";
+import type { EvalImageContent } from "./image-resize.ts";
 import type { EvalLanguage, EvalToolDetails } from "./types.ts";
 
 export type EvalDetachedCellState = "queued" | "running" | "detached" | "completed" | "failed" | "cancelled";
@@ -24,6 +25,8 @@ export interface EvalDetachedCellSnapshot {
 export interface EvalDetachedCellNotification {
 	readonly cellId: string;
 	readonly content: string;
+	/** Images the cell displayed, delivered with the notification the way a foreground result delivers them. */
+	readonly images?: readonly EvalImageContent[];
 }
 
 export interface EvalDetachedCellNotifier {

package/src/tool/detached-cell-manager.ts

@@ -13,7 +13,7 @@ import type {
 	EvalDetachedCellSnapshot,
 	EvalDetachedCellStatusEntry,
 } from "./detached-cell-contract.ts";
-import { currentDetachedResult, detachedErrorResult, snapshotDetachedCell } from "./detached-cell-snapshot.ts";
+import { cancelledDetachedResult, detachedErrorResult, snapshotDetachedCell } from "./detached-cell-snapshot.ts";
 import {
 	activeDetachedCellReuseError,
 	allowsDetachedCellTransition,
@@ -36,7 +36,6 @@ export type {
 } from "./detached-cell-contract.ts";
 
 export class EvalDetachedCellManager {
-	readonly #artifactsDir: string | undefined;
 	readonly #onStatusChange: ((entries: readonly EvalDetachedCellStatusEntry[]) => void) | undefined;
 	readonly #onWakeSourceState: ((state: WakeSourceState) => void) | undefined;
 	readonly #cells = new Map<string, ManagedCell>();
@@ -49,7 +48,6 @@ export class EvalDetachedCellManager {
 	readonly #maxDetachedCells: number;
 
 	constructor(options: EvalDetachedCellManagerOptions = {}) {
-		this.#artifactsDir = options.artifactsDir;
 		this.#onStatusChange = options.onStatusChange;
 		this.#onWakeSourceState = options.onWakeSourceState;
 		this.#notificationQueue = new DetachedNotificationQueue(options.notifier);
@@ -85,7 +83,6 @@ export class EvalDetachedCellManager {
 		const cell = createManagedCell({
 			cellId,
 			input,
-			artifactsDir: this.#artifactsDir,
 			now: this.#now,
 			defaultHardLimitSeconds: this.#hardLimitSeconds,
 			defaultRunBudgetSeconds: this.#runBudgetSeconds,
@@ -239,7 +236,6 @@ export class EvalDetachedCellManager {
 						await cell.interruptOutcome?.promise;
 						return this.#snapshot(cell);
 					},
-					spillPath: cell.spillPath,
 				});
 			}
 		}
@@ -260,7 +256,7 @@ export class EvalDetachedCellManager {
 			return;
 		}
 		if (foreground) {
-			if (this.#settle(cell, "cancelled", currentDetachedResult(cell))) cell.onKill?.(expiry.error);
+			if (this.#settle(cell, "cancelled", cancelledDetachedResult(cell))) cell.onKill?.(expiry.error);
 			return;
 		}
 		await this.#cancel(cell, expiry.error.message);
@@ -269,7 +265,7 @@ export class EvalDetachedCellManager {
 	#cancelQueued(cell: ManagedCell, reason: string, error = new Error(reason)): void {
 		const dequeued = cell.kernel?.cancelQueued(cell.cellId, reason) ?? false;
 		cell.stateRetained = true;
-		this.#settle(cell, "cancelled", currentDetachedResult(cell));
+		this.#settle(cell, "cancelled", cancelledDetachedResult(cell));
 		// Acquisition/reset has no queue promise yet; its execution has no interrupt target either.
 		if (!dequeued) cell.onKill?.(error);
 	}
@@ -278,7 +274,7 @@ export class EvalDetachedCellManager {
 		const outcome = Promise.withResolvers<void>();
 		cell.interruptOutcome = outcome;
 		try {
-			if (!this.#settle(cell, "cancelled", currentDetachedResult(cell)) || cell.kernel === undefined) return;
+			if (!this.#settle(cell, "cancelled", cancelledDetachedResult(cell)) || cell.kernel === undefined) return;
 			const handle = await cell.kernel.interrupt(reason, cell.cellId);
 			cell.interruptNote = handle.note;
 			cell.stateRetained = await handle.stateRetained;

package/src/tool/detached-cell-notification.ts

@@ -1,61 +1,21 @@
-import { mkdir, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
 import type { EvalDetachedCellNotification, EvalDetachedCellSnapshot } from "./detached-cell-manager.ts";
 import { interruptionStateNote, unknownInterruptionStateNote } from "./interrupt-note.ts";
 import type { EvalKernelState, EvalMemoryDetails } from "./types.ts";
 
-const NOTIFICATION_TAIL_BYTES = 512;
-
-export function detachedNotificationSpillPath(artifactsDir: string | undefined, cellId: string): string | undefined {
-	if (artifactsDir === undefined) return undefined;
-	return join(artifactsDir, "local", `detached-eval-${safeCellId(cellId)}.log`);
-}
-
-export async function buildDetachedCellNotification(
-	snapshot: EvalDetachedCellSnapshot,
-	spillPath: string | undefined,
-): Promise<EvalDetachedCellNotification> {
-	const body = notificationBody(snapshot);
-	const overflow = Buffer.byteLength(body, "utf8") > NOTIFICATION_TAIL_BYTES;
-	let spillNotice = "";
-	if (overflow && spillPath !== undefined) {
-		try {
-			await mkdir(dirname(spillPath), { recursive: true });
-			await writeFile(spillPath, body, "utf8");
-			// The agent read tool resolves plain paths only, so the notice must carry
-			// the absolute spill path, never the kernel-helper local:// scheme.
-			spillNotice = `\nBuffered output overflowed; full output: ${spillPath}`;
-		} catch (error) {
-			const message = error instanceof Error ? error.message : String(error);
-			spillNotice = `\nBuffered output overflow could not be spilled: ${message}`;
-		}
-	}
-	return {
-		cellId: snapshot.cellId,
-		content: `${overflow ? notificationPreview(snapshot) : body}${overflow ? "\n[…notification tail capped…]" : ""}${spillNotice}`,
-	};
-}
-
-function notificationBody(cell: EvalDetachedCellSnapshot): string {
-	const outcome = outcomeOf(cell);
-	const resultText = textContent(cell);
-	const stateNote = stateNoteOf(cell);
-	return [
-		`<system-reminder>Detached eval cell ${cell.cellId} (${cell.language}) ${outcome}.`,
-		resultText.length === 0 ? "(no output)" : resultText,
-		`${stateNote}</system-reminder>`,
-	].join("\n");
+/**
+ * A detached cell's completion carries the same text its result would have shown in the foreground: the output sink
+ * already bounded it (the configured head, the tail, the middle marker and the artifact notice), plus its images.
+ */
+export function buildDetachedCellNotification(snapshot: EvalDetachedCellSnapshot): EvalDetachedCellNotification {
+	const images = snapshot.result.content.filter((part) => part.type === "image");
+	return { cellId: snapshot.cellId, content: notificationText(snapshot, textContent(snapshot)), images };
 }
 
-function notificationPreview(cell: EvalDetachedCellSnapshot): string {
-	const outcome = outcomeOf(cell);
-	const resultText = textContent(cell);
-	const stateNote = stateNoteOf(cell);
+function notificationText(cell: EvalDetachedCellSnapshot, output: string): string {
 	return [
-		`<system-reminder>Detached eval cell ${cell.cellId} (${cell.language}) ${outcome}.`,
-		"Buffered output tail:",
-		truncateTailUtf8(resultText, NOTIFICATION_TAIL_BYTES),
-		`${stateNote}</system-reminder>`,
+		`<system-reminder>Detached eval cell ${cell.cellId} (${cell.language}) ${outcomeOf(cell)}.`,
+		output.length === 0 ? "(no output)" : output,
+		`${stateNoteOf(cell)}</system-reminder>`,
 	].join("\n");
 }
 
@@ -101,15 +61,3 @@ export function memoryStateNote(memory: EvalMemoryDetails | undefined): string {
 		return "The kernel was restarted before this cell ran - globals from earlier cells are gone; this cell's variables are available to the next eval cell.";
 	return "Kernel state updated - variables are available to the next eval cell.";
 }
-
-function safeCellId(cellId: string): string {
-	return cellId.replace(/[^a-zA-Z0-9_-]/gu, "_");
-}
-
-function truncateTailUtf8(text: string, maxBytes: number): string {
-	if (Buffer.byteLength(text, "utf8") <= maxBytes) return text;
-	const bytes = Buffer.from(text, "utf8");
-	let start = bytes.length - maxBytes;
-	while (start < bytes.length && (bytes[start] & 0xc0) === 0x80) start++;
-	return bytes.subarray(start).toString("utf8");
-}

package/src/tool/detached-cell-snapshot.ts

@@ -63,6 +63,23 @@ export function currentDetachedResult(cell: DetachedCellResultSource): AgentTool
 	return cell.terminalResult ?? cell.liveResult?.() ?? fallbackResult(cell.input);
 }
 
+/**
+ * The result a cell cancelled before its handler finished settles with: its buffered output, not the live progress
+ * frame ("1/1 cells running"), so a stopped cell never reads as still running.
+ */
+export function cancelledDetachedResult(cell: DetachedCellResultSource): AgentToolResult<EvalToolDetails> {
+	if (cell.terminalResult !== undefined) return cell.terminalResult;
+	const current = currentDetachedResult(cell);
+	const output = detachedOutputTail(current);
+	return {
+		content: [
+			{ type: "text", text: output.length > 0 ? output : "(no output)" },
+			...current.content.filter((part) => part.type === "image"),
+		],
+		details: current.details,
+	};
+}
+
 export function detachedErrorResult(cell: DetachedCellResultSource, error: Error): AgentToolResult<EvalToolDetails> {
 	const current = currentDetachedResult(cell);
 	const output = detachedOutputTail(current);

package/src/tool/detached-eval-result.ts

@@ -46,9 +46,7 @@ function createEvalListResult(cellManager: EvalDetachedCellManager): AgentToolRe
 			language: snapshot.language,
 			state: snapshot.state,
 			startedAtMs: snapshot.startedAtMs,
-			...(snapshot.queuedBehind === undefined || snapshot.queuedBehind.length === 0
-				? {}
-				: { queuedBehind: [...snapshot.queuedBehind] }),
+			...(snapshot.queuedBehind === undefined ? {} : { queuedBehind: [...snapshot.queuedBehind] }),
 			...(summary ? { summary } : {}),
 		};
 	});
@@ -60,7 +58,7 @@ function createEvalListResult(cellManager: EvalDetachedCellManager): AgentToolRe
 				" ",
 			);
 			const elapsed = Math.floor(snapshot.result.details.durationMs / 1000);
-			const queued = cell.queuedBehind === undefined ? "" : ` queued behind ${cell.queuedBehind.join(", ")}`;
+			const queued = cell.queuedBehind === undefined ? "" : ` ${queuedPhrase(cell.queuedBehind, cell.language)}`;
 			return `${cell.cellId} ${cell.language} ${cell.state} ${elapsed}s${queued} - ${preview}`;
 		})
 		.join("\n");
@@ -76,11 +74,13 @@ export function resultAfterDetach(
 	otherLiveCells: number,
 ): AgentToolResult<EvalToolDetails> {
 	if (snapshot.state !== "detached" && snapshot.state !== "running") return createDetachedControlResult(snapshot);
-	const predecessors = snapshot.queuedBehind?.join(", ");
+	const queuedBehind = snapshot.queuedBehind;
 	const text =
-		predecessors === undefined
+		queuedBehind === undefined
 			? `Eval cell ${snapshot.cellId} detached and is running in the ${input.language} kernel (${otherLiveCells} other live cells). Completion arrives as a notification; do not re-run it. eval({ action: "peek" | "stop", cell_id }) or eval({ action: "list" }).`
-			: `Eval cell ${snapshot.cellId} is queued behind ${predecessors} in the ${input.language} kernel and detached; it runs after ${predecessors} and completes as one notification. peek/stop/list with eval({ action, cell_id })`;
+			: queuedBehind.length === 0
+				? `Eval cell ${snapshot.cellId} is detached and waiting for the ${input.language} kernel to be ready; it runs first once the kernel is ready and completes as one notification. peek/stop/list with eval({ action, cell_id })`
+				: `Eval cell ${snapshot.cellId} is queued behind ${queuedBehind.join(", ")} in the ${input.language} kernel and detached; it runs after ${queuedBehind.join(", ")} and completes as one notification. peek/stop/list with eval({ action, cell_id })`;
 	return {
 		content: [
 			{
@@ -164,6 +164,12 @@ export function resultForDetachedState(
 	};
 }
 
+function queuedPhrase(queuedBehind: readonly string[], language: string): string {
+	return queuedBehind.length === 0
+		? `waiting for the ${language} kernel to be ready`
+		: `queued behind ${queuedBehind.join(", ")}`;
+}
+
 function textContent(result: AgentToolResult<EvalToolDetails>): string {
 	return result.content
 		.filter((part) => part.type === "text")

package/src/tool/detached-notification-queue.ts

@@ -3,7 +3,6 @@ import { buildDetachedCellNotification } from "./detached-cell-notification.ts";
 
 export interface PendingDetachedNotification {
 	readonly snapshot: () => EvalDetachedCellSnapshot | Promise<EvalDetachedCellSnapshot>;
-	readonly spillPath: string | undefined;
 }
 
 export class DetachedNotificationQueue {
@@ -30,7 +29,7 @@ export class DetachedNotificationQueue {
 		const flush = Promise.resolve().then(async () => {
 			const pending = this.#pending.splice(0);
 			const notifications = await Promise.all(
-				pending.map(async (item) => await buildDetachedCellNotification(await item.snapshot(), item.spillPath)),
+				pending.map(async (item) => buildDetachedCellNotification(await item.snapshot())),
 			);
 			this.#notifier?.notify(notifications);
 		});

package/src/tool/eval-request.ts

@@ -17,9 +17,19 @@ export function normalizeEvalSummary(value: unknown): string | undefined {
 	return normalized.length === 0 ? undefined : normalized;
 }
 
+export class EvalIsolateInvalidError extends TypeError {
+	readonly name = "EvalIsolateInvalidError";
+	readonly code = "eval_isolate_invalid";
+
+	constructor(reason: string) {
+		super(`eval_isolate_invalid: ${reason}`);
+	}
+}
+
 export function parseEvalRequest(
 	params: unknown,
 	enabledLanguages: readonly EvalLanguage[] = evalLanguageOrder,
+	options: { readonly sandbox?: boolean } = {},
 ): EvalToolRequest {
 	if (!isRecord(params)) throw new TypeError("eval parameters must be an object");
 	if (params.action === "list") return { action: "list" };
@@ -30,7 +40,9 @@ export function parseEvalRequest(
 	}
 	if (params.action !== undefined && params.action !== "run")
 		throw new TypeError(`Unknown eval action "${String(params.action)}"`);
-	if (!isEvalLanguage(params.language)) throw new TypeError(evalRunRequiresLanguageMessage(enabledLanguages));
+	if (params.language === undefined) throw new TypeError(evalRunRequiresLanguageMessage(enabledLanguages));
+	if (!isEvalLanguage(params.language))
+		throw new TypeError(`eval run language must be one of: ${enabledLanguages.join(", ")}`);
 	if (typeof params.code !== "string")
 		throw new TypeError("eval run requires code — the cell body to execute, verbatim");
 	const summary = normalizeEvalSummary(params.summary);
@@ -40,6 +52,15 @@ export function parseEvalRequest(
 		);
 	if (params.on_timeout !== undefined && params.on_timeout !== "detach" && params.on_timeout !== "error")
 		throw new TypeError(`Unknown eval on_timeout value "${String(params.on_timeout)}"`);
+	if (params.isolate !== undefined && params.isolate !== false) {
+		if (params.isolate !== true) throw new EvalIsolateInvalidError("isolate must be true or false");
+		if (options.sandbox !== true) {
+			throw new EvalIsolateInvalidError("sandbox cells are turned off (set sandbox.enabled in codemode settings)");
+		}
+		if (params.language !== "js")
+			throw new EvalIsolateInvalidError('sandbox cells run JavaScript only (language: "js")');
+		if (params.reset === true) throw new EvalIsolateInvalidError("a sandbox cell starts fresh; reset does not apply");
+	}
 	return {
 		language: params.language,
 		code: params.code,
@@ -48,6 +69,7 @@ export function parseEvalRequest(
 		...(typeof params.timeout === "number" ? { timeout: params.timeout } : {}),
 		...(params.on_timeout === "detach" || params.on_timeout === "error" ? { on_timeout: params.on_timeout } : {}),
 		...(typeof params.reset === "boolean" ? { reset: params.reset } : {}),
+		...(params.isolate === true ? { isolate: true } : {}),
 	};
 }
 

package/src/tool/eval-tool-options.ts

@@ -8,6 +8,8 @@ import type {
 import type { EvalSchemaToolInfo } from "../bridges/schema-bridge.ts";
 import type { CompletionRequest, CompletionResult } from "../completion/handler.ts";
 import type { ResolvedCodemodeSettings } from "../config/settings.ts";
+import type { JsEnvironments } from "../environments/js-environments.ts";
+import type { PythonEnvironments } from "../environments/python-environments.ts";
 import type { EvalExecutionTracker } from "../extension/session-manager.ts";
 import type { HandleRegistry } from "../handles/handle-registry.ts";
 import type { EvalTimeoutFactory } from "./cell-execution.ts";
@@ -69,6 +71,10 @@ export interface CreateEvalToolOptions {
 	readonly bunSkillPath?: string;
 	/** Kernel globals of the tools active when a cell is submitted; read once per cell. */
 	readonly kernelPreludes?: () => readonly KernelPreludeContribution[];
+	/** The session's Python environments: `%pip` / `%environment` cells and the import root of every Python cell. */
+	readonly pythonEnvironments?: PythonEnvironments;
+	/** The session's managed JavaScript packages: `%bun add` / `%npm add` cells and the bare-import fallback root. */
+	readonly jsEnvironments?: JsEnvironments;
 	/** Contributions whose documentation lines the description lists; snapshot taken when the tool is (re)registered. */
 	readonly promptKernelPreludes?: readonly KernelPreludeContribution[];
 }

package/src/tool/eval-tool.ts

@@ -1,5 +1,6 @@
 import type { AgentToolResult, ToolDefinition } from "@code-yeongyu/senpi";
 import type { TUnsafe } from "typebox";
+import { resolveAdvertiseHelpers, resolveSandbox } from "../config/feature-settings.ts";
 import {
 	DEFAULT_FOREGROUND_WINDOW_SECONDS,
 	defaultCodemodeSettings,
@@ -8,7 +9,12 @@ import {
 import { buildEvalPrompt } from "../prompt/eval-prompt.ts";
 import { EvalDetachedCellManager } from "./detached-cell-manager.ts";
 import { executeEvalControl } from "./detached-eval-result.ts";
-import { isEvalControlRequest, normalizeEvalSummary, parseEvalRequest } from "./eval-request.ts";
+import {
+	EvalIsolateInvalidError,
+	isEvalControlRequest,
+	normalizeEvalSummary,
+	parseEvalRequest,
+} from "./eval-request.ts";
 import type { CreateEvalToolOptions } from "./eval-tool-options.ts";
 import { runEvalCell } from "./run-eval-cell.ts";
 import {
@@ -43,9 +49,11 @@ export function createEvalTool(options: CreateEvalToolOptions) {
 		foregroundWindowSeconds,
 		hardLimitSeconds: options.hardLimitSeconds ?? defaultEvalDeadlineSeconds.hardLimitSeconds,
 	};
-	const parameters = createEvalInputSchema(options.enabledLanguages, deadlines);
+	const sandbox = resolveSandbox(options.settings ?? defaultCodemodeSettings).enabled;
+	const parameters = createEvalInputSchema(options.enabledLanguages, deadlines, { sandbox });
 	const prompt = buildEvalPrompt(options.enabledLanguages, {
 		spawns: options.spawns ?? false,
+		...(resolveAdvertiseHelpers(options.settings ?? defaultCodemodeSettings) ? { advertiseHelpers: true } : {}),
 		monitor: options.monitor,
 		maxDetachedCells,
 		runBudgetSeconds: deadlines.runBudgetSeconds,
@@ -74,9 +82,14 @@ export function createEvalTool(options: CreateEvalToolOptions) {
 	async function execute(
 		...[toolCallId, params, signal, onUpdate, ctx]: EvalExecuteArgs<EvalToolRequest>
 	): Promise<AgentToolResult<EvalResultDetails>> {
-		const request = parseEvalRequest(params, languages);
+		const request = parseEvalRequest(params, languages, { sandbox });
 		if (isEvalControlRequest(request)) return await executeEvalControl(cellManager, request);
-		if (options.proxyExecutor) return await options.proxyExecutor(request, signal);
+		if (options.proxyExecutor) {
+			// A proxy runs cells elsewhere and knows nothing of sandbox cells: an isolated cell must never run unisolated.
+			if ("isolate" in request && request.isolate === true)
+				throw new EvalIsolateInvalidError("isolate: true is not available through this eval proxy");
+			return await options.proxyExecutor(request, signal);
+		}
 		if (!languages.includes(request.language))
 			throw new RangeError(
 				`Unsupported eval language "${request.language}". Enabled languages: ${languages.join(", ")}`,

package/src/tool/interrupt-note.ts

@@ -26,9 +26,8 @@ export async function describeTimeoutState(
 	);
 	if (outcome === undefined) error.message = fallbackTimeoutMessage(error.message);
 	else if (outcome.retained)
-		error.message = `${error.message} The kernel remains running; its existing variables are preserved.`;
-	else
-		error.message = `${error.message} The kernel was unresponsive and restarted; variables from earlier cells are lost.`;
+		error.message = `${error.message} The kernel was not restarted; variables from earlier cells are kept.`;
+	else error.message = `${error.message} The kernel was restarted; variables from earlier cells are lost.`;
 	if (outcome?.note !== undefined) error.message = `${error.message} ${outcome.note.trim()}`;
 	return error;
 }
@@ -63,8 +62,8 @@ const LANGUAGE_LABEL: Record<EvalLanguage, string> = {
 export function interruptionStateNote(language: EvalLanguage, stateRetained: boolean | undefined): string | undefined {
 	if (stateRetained === undefined) return undefined;
 	const label = LANGUAGE_LABEL[language];
-	if (stateRetained) return `${label} was interrupted and remains running; its existing variables are preserved.`;
-	return `${label} was unresponsive to interrupt and was restarted; variables from earlier cells are lost.`;
+	if (stateRetained) return `The ${label} was not restarted; variables from earlier cells are kept.`;
+	return `The ${label} was restarted; variables from earlier cells are lost.`;
 }
 
 export function unknownInterruptionStateNote(language: EvalLanguage): string {

package/src/tool/live-headline.ts

@@ -0,0 +1,60 @@
+import { sanitizeTerminalLabel, visibleWidth } from "@code-yeongyu/senpi";
+import { type EvalCellResult, type EvalLanguage, evalLanguageOrder } from "./types.ts";
+
+const HEADLINED_STATUSES: ReadonlySet<EvalCellResult["status"]> = new Set(["pending", "queued", "running", "detached"]);
+
+/**
+ * A collapsed headline never wraps the frame: it gets what the language, state and timing leave on the line. This
+ * floor (in screen cells) only keeps a word or two visible in very narrow terminals.
+ */
+const MIN_HEADLINE_CELLS = 8;
+
+export function leadsWithHeadline(status: EvalCellResult["status"]): boolean {
+	return HEADLINED_STATUSES.has(status);
+}
+
+/**
+ * What an in-progress cell is doing, in one line: its summary, or else the first line of its code that has content once sanitized (the
+ * oh-my-pi fallback), or an ellipsis while the arguments are still streaming in. Collapsed rows cut it to
+ * `maxCells` screen cells (a wide character takes two), so the headline stays one line. Whichever is chosen is
+ * sanitized before it is measured, so escape and control characters never reach the row (senpi#2831, senpi#2839).
+ */
+export function liveHeadline(
+	summary: string | undefined,
+	code: string | undefined,
+	maxCells: number | undefined,
+): string {
+	const text = (summary === undefined ? "" : sanitizeTerminalLabel(summary)) || firstCodeLine(code) || "…";
+	const limit = maxCells === undefined ? undefined : Math.max(MIN_HEADLINE_CELLS, maxCells);
+	if (limit === undefined || visibleWidth(text) <= limit) return text;
+	return `${cellPrefix(text, limit - 1)}…`;
+}
+
+// A plain cut by screen cells: the headline is styled by the caller, so no reset codes may be inserted here.
+function cellPrefix(text: string, cells: number): string {
+	let kept = "";
+	let used = 0;
+	for (const { segment } of new Intl.Segmenter(undefined, { granularity: "grapheme" }).segment(text)) {
+		const width = visibleWidth(segment);
+		if (used + width > cells) break;
+		kept += segment;
+		used += width;
+	}
+	return kept;
+}
+
+export function knownLanguage(language: unknown): EvalLanguage | undefined {
+	return evalLanguageOrder.find((known) => known === language);
+}
+
+// The first line with something to show once it is sanitized: a line of only escape or control characters is skipped
+// (senpi#2850), and the later lines never reach the row.
+function firstCodeLine(code: string | undefined): string | undefined {
+	if (code === undefined) return undefined;
+	// Stops at the first line with content, so a long cell is not sanitized line by line on every frame.
+	for (const line of code.split("\n")) {
+		const clean = sanitizeTerminalLabel(line);
+		if (clean.length > 0) return clean;
+	}
+	return undefined;
+}