@code-yeongyu/senpi-codemode 2026.10.5 → 2026.10.6

package/CHANGELOG.md

@@ -12,6 +12,28 @@
 
 ### Removed
 
+## [2026.10.6] - 2026-10-04
+
+### Breaking Changes
+
+### Added
+
+- An opt-in `memory.idleParkMinutes` setting (off by default) closes a kernel that had no cell running or queued for that many minutes to give its memory back; the next cell starts a fresh kernel and its result says every earlier global is lost ([#2452](https://github.com/code-yeongyu/senpi/issues/2452)).
+- Ruby eval results name their largest globals, and Ruby and Julia kernels now get the same large-memory notice as JavaScript and Python when the interpreter footprint crosses `memory.noticeMb` ([#2452](https://github.com/code-yeongyu/senpi/issues/2452)).
+- Julia eval results name their largest globals in that notice ([#2452](https://github.com/code-yeongyu/senpi/issues/2452)).
+
+### Changed
+- Kernel tool descriptors may name any eval language (`js`, `py`, `rb`, `jl`), not only `js`; today only JavaScript kernels define tools, so nothing a session sees changes ([#2452](https://github.com/code-yeongyu/senpi/issues/2452)).
+
+### Fixed
+- A Ruby or Julia kernel whose start hangs no longer leaves its cells waiting forever: startup fails, naming the stage it stalled in, once the runner has printed nothing, changed no stage and its process group has used no CPU for 30 s, so a slow but busy start (a cold Julia compiling its prelude) is never cut off ([#2452](https://github.com/code-yeongyu/senpi/issues/2452)).
+- A `codemode.json` that names a key this version does not know no longer throws away every other setting: the unknown key gets one warning and the rest still apply (known nested objects stay strict). Optional keys for upcoming features (`environments`, `isolation`, `sandbox`, `prompt.advertiseHelpers`, `kernelTools`, `languages.pyInterpreter`) parse with today's behaviour as their defaults ([#2452](https://github.com/code-yeongyu/senpi/issues/2452)).
+
+- A Python cell's host calls (`tool.*`, `completion`) no longer go through a configured HTTP proxy: the loopback bridge request ignores proxy settings from the environment and, on Windows, the registry, so a proxy can't refuse a `127.0.0.1` call that never needed it ([#2619](https://github.com/code-yeongyu/senpi/issues/2619)).
+- A JavaScript memory report no longer runs user code: array elements are read through their own descriptors (an index accessor is skipped and the estimate marked approximate), and typed arrays, buffers, Blob, Map and Set are sized through the built-in getters, so a subclass that overrides `byteLength` or `size` is never called ([#2452](https://github.com/code-yeongyu/senpi/issues/2452)).
+
+### Removed
+
 ## [2026.10.5] - 2026-10-03
 
 ### Breaking Changes

package/README.md

@@ -156,17 +156,31 @@ Configuration is loaded in this order:
 | `outputSink.maxColumns` | `768` | Maximum columns per printed output line; `0` disables column clamping. A cell's return value is never column-clamped (the byte and line budgets still apply). |
 | `statusEvents` | `true` | Enables kernel status-event forwarding and rendering. Each cell retains at most 100 status rows; after overflow, one omitted-count row precedes the latest 99 events. |
 | `memory.gcWatermarkMb` | `256` | JavaScript kernel: a finished cell whose heap reached this size and grew runs a full collection before its result; whenever at least this much stays live, an idle full collection runs about a second after the cell, so dropped globals return their memory without a reset. Python kernel: a finished cell whose process footprint reached this size and grew runs `gc.collect()` (plus glibc `malloc_trim(0)` on Linux) before its result, and while at least this much stays live the next cells collect too (at most 1/20 of the time), so `del rows` returns its memory. `0` disables. Env override: `SENPI_CODEMODE_MEMORY_GC_WATERMARK_MB`. |
-| `memory.noticeMb` | `1024` | JavaScript and Python kernels: when live memory after a collection (JS heap, Python process footprint) reaches this size (first time, or 25% more than at the last notice), the result gets one bracketed notice naming the largest globals and how to drop them (`rows = undefined`, `del rows`), plus `details.memory`. Ruby and Julia get no notice. `0` disables. Env override: `SENPI_CODEMODE_MEMORY_NOTICE_MB`. |
+| `memory.noticeMb` | `1024` | When live memory (JS heap or Python footprint after a collection; Ruby and Julia interpreter footprint read by the host after each cell) reaches this size (first time, or 25% more than at the last notice), the result gets one bracketed notice naming the largest globals and how to drop them (`rows = undefined`, `del rows`, `rows = nil`, `rows = nothing`), plus `details.memory`. `0` disables. Env override: `SENPI_CODEMODE_MEMORY_NOTICE_MB`. |
 | `memory.ceilingMb` | a quarter of physical memory, 2048-8192 | Every kernel (JS heap and Python footprint after a collection; Ruby and Julia interpreter footprint read by the host after each result, without a globals list): when live memory reaches this size, the result says so and the kernel restarts once no cell is running or queued on it; the next result says it was restarted (`details.memory.recycled`). `0` disables. Env override: `SENPI_CODEMODE_MEMORY_CEILING_MB`. Non-zero memory thresholds must satisfy watermark <= notice <= ceiling, otherwise all three use their defaults. |
 | `memory.retainedResultsMb` | `32` | In-memory byte budget (MiB) for the settled cells kept for `peek`/`list`, on top of the 32-cell count cap; the oldest go first and the newest is always kept. `0` keeps only the count cap. Env override: `SENPI_CODEMODE_RETAINED_RESULTS_MB` (a non-negative integer). |
 | `memory.retainedImagesMb` | `256` | Disk budget (MiB) for settled-cell images. Images of settled cells (foreground and detached) are written as base64 files under `<session artifacts>/settled-images/` instead of staying in memory, and `peek` reads them back, so it returns the full result. Beyond the budget the oldest files are deleted first; an evicted cell's files are deleted with it; the directory is removed when the session ends. A `peek` whose image file is gone returns the text plus a one-line note. `0` keeps only the count cap. Env override: `SENPI_CODEMODE_RETAINED_IMAGES_MB` (a non-negative integer). |
+| `memory.idleParkMinutes` | `0` | Off by default. When greater than 0, a kernel with no cell running or queued for this many minutes is closed to give its memory back, and the next cell for that language starts a fresh one; that cell's result says the kernel was restarted and every earlier global is lost. Applies to every language. |
+| `languages.pyInterpreter` | unset | Explicit Python interpreter path. Unset keeps today's `PATH` detection. |
+| `environments.managedRoot` | unset | Root directory for managed per-session environments; unset uses the session's default location. |
+| `environments.autoProvision` | `true` | Lets installs provision a managed environment. `false` makes installs refuse with `environment_installer_unavailable`. |
+| `environments.js.installer` | `auto` | Installer for the managed JavaScript environment: `auto`, `bun` or `npm`. |
+| `environments.py.installer` | `pip` | Installer for the managed Python environment. |
+| `isolation.js` | `worker` | JavaScript kernel isolation: `worker` (today's worker thread) or `process`. Env override: `SENPI_CODEMODE_JS_ISOLATION`. |
+| `sandbox.enabled` | `false` | Allows sandbox cells. While `false` the sandbox option is neither accepted nor advertised. |
+| `sandbox.memoryMb` | `64` | Memory cap (MiB) for a sandbox cell. Env override: `SENPI_CODEMODE_SANDBOX_MEMORY_MB` (a positive integer wins). |
+| `sandbox.timeoutSeconds` | `300` | Time limit for a sandbox cell. |
+| `prompt.advertiseHelpers` | `false` | When `true`, one pointer line to `tool_schema('eval:helpers')` is appended to the eval description. |
+| `kernelTools.enabled` | `true` | Allows cells to define kernel tools (`tool(fn)`, `@tool`). `false` makes them refuse with `tools_unavailable`. |
+
+The `languages.pyInterpreter`, `environments.*`, `isolation.*`, `sandbox.*`, `prompt.*` and `kernelTools.*` keys are accepted and validated now, with the defaults shown, which match today's behaviour. The effect each of those rows describes takes effect when its feature ships; until then, setting a key changes nothing.
 
 `SENPI_CODEMODE_PY`, `SENPI_CODEMODE_JS`, `SENPI_CODEMODE_RB`, and
 `SENPI_CODEMODE_JL` override the corresponding file setting. `1` or `true`
 enables; `0` or `false` disables. Any other value leaves the file setting in
 effect.
 
-Malformed JSON or invalid settings fall back to defaults with a warning.
+A top-level key this version does not know is ignored with one warning naming it, and the rest of the file still applies, so a settings file written for a newer senpi keeps working. Malformed JSON, or an invalid value or an unknown key inside a known setting, falls back to all defaults with a warning.
 The detached-cell environment override uses the run-budget parser: a positive
 base-10 integer wins over the file value; zero, negative, and malformed values
 leave the file value in effect.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/senpi-codemode",
-	"version": "2026.10.5",
+	"version": "2026.10.6",
 	"description": "Source-only senpi extension package for codemode evaluation tools",
 	"type": "module",
 	"main": "./src/index.ts",
@@ -32,14 +32,14 @@
 	},
 	"dependencies": {
 		"@babel/parser": "8.0.4",
-		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@2026.10.5",
+		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@2026.10.6",
 		"typebox": "1.3.34"
 	},
 	"peerDependencies": {
-		"@code-yeongyu/senpi": "2026.10.5"
+		"@code-yeongyu/senpi": "2026.10.6"
 	},
 	"devDependencies": {
-		"@code-yeongyu/senpi": "2026.10.5"
+		"@code-yeongyu/senpi": "2026.10.6"
 	},
 	"keywords": [
 		"senpi",

package/src/bridge/kernel-tools-protocol.ts

@@ -29,7 +29,7 @@ export const kernelToolDescriptorSchema = Type.Object({
 	name: Type.String({ minLength: 1 }),
 	description: Type.String(),
 	input_schema: Type.Unknown(),
-	language: Type.Literal("js"),
+	language: Type.Union([Type.Literal("js"), Type.Literal("py"), Type.Literal("rb"), Type.Literal("jl")]),
 	kernel_generation: Type.Integer({ minimum: 0 }),
 	definition_revision: Type.Integer({ minimum: 1 }),
 });

package/src/config/feature-settings.ts

@@ -0,0 +1,110 @@
+import type { Static } from "typebox";
+import { Type } from "typebox";
+
+type Environment = Readonly<Record<string, string | undefined>>;
+
+export const JS_ISOLATION_ENVIRONMENT_FLAG = "SENPI_CODEMODE_JS_ISOLATION";
+export const SANDBOX_MEMORY_ENVIRONMENT_FLAG = "SENPI_CODEMODE_SANDBOX_MEMORY_MB";
+
+export const featureSettingsProperties = {
+	environments: Type.Optional(
+		Type.Object(
+			{
+				managedRoot: Type.Optional(Type.String({ minLength: 1 })),
+				autoProvision: Type.Optional(Type.Boolean()),
+				js: Type.Optional(
+					Type.Object(
+						{ installer: Type.Union([Type.Literal("auto"), Type.Literal("bun"), Type.Literal("npm")]) },
+						{ additionalProperties: false },
+					),
+				),
+				py: Type.Optional(Type.Object({ installer: Type.Literal("pip") }, { additionalProperties: false })),
+			},
+			{ additionalProperties: false },
+		),
+	),
+	isolation: Type.Optional(
+		Type.Object(
+			{ js: Type.Optional(Type.Union([Type.Literal("worker"), Type.Literal("process")])) },
+			{ additionalProperties: false },
+		),
+	),
+	sandbox: Type.Optional(
+		Type.Object(
+			{
+				enabled: Type.Optional(Type.Boolean()),
+				memoryMb: Type.Optional(Type.Integer({ minimum: 1 })),
+				timeoutSeconds: Type.Optional(Type.Integer({ minimum: 1 })),
+			},
+			{ additionalProperties: false },
+		),
+	),
+	prompt: Type.Optional(
+		Type.Object({ advertiseHelpers: Type.Optional(Type.Boolean()) }, { additionalProperties: false }),
+	),
+	kernelTools: Type.Optional(Type.Object({ enabled: Type.Optional(Type.Boolean()) }, { additionalProperties: false })),
+};
+
+const featureSettingsSchema = Type.Object(featureSettingsProperties);
+
+export type CodemodeFeatureSettings = Static<typeof featureSettingsSchema>;
+
+export type JsIsolation = "worker" | "process";
+
+export interface ResolvedSandbox {
+	readonly enabled: boolean;
+	readonly memoryMb: number;
+	readonly timeoutSeconds: number;
+}
+
+export interface ResolvedEnvironments {
+	readonly managedRoot?: string;
+	readonly autoProvision: boolean;
+	readonly jsInstaller: "auto" | "bun" | "npm";
+	readonly pyInstaller: "pip";
+}
+
+export function pickFeatureSettings(input: CodemodeFeatureSettings): CodemodeFeatureSettings {
+	return {
+		...(input.environments === undefined ? {} : { environments: input.environments }),
+		...(input.isolation === undefined ? {} : { isolation: input.isolation }),
+		...(input.sandbox === undefined ? {} : { sandbox: input.sandbox }),
+		...(input.prompt === undefined ? {} : { prompt: input.prompt }),
+		...(input.kernelTools === undefined ? {} : { kernelTools: input.kernelTools }),
+	};
+}
+
+/** The environment wins over the file; an unknown value is ignored. Default: today's worker-thread kernel. */
+export function resolveJsIsolation(settings: CodemodeFeatureSettings, env: Environment = process.env): JsIsolation {
+	const fromEnv = env[JS_ISOLATION_ENVIRONMENT_FLAG];
+	if (fromEnv === "worker" || fromEnv === "process") return fromEnv;
+	return settings.isolation?.js ?? "worker";
+}
+
+/** Off by default; the environment's memory cap wins over the file when it is a positive integer. */
+export function resolveSandbox(settings: CodemodeFeatureSettings, env: Environment = process.env): ResolvedSandbox {
+	const fromEnv = Number.parseInt(env[SANDBOX_MEMORY_ENVIRONMENT_FLAG] ?? "", 10);
+	return {
+		enabled: settings.sandbox?.enabled ?? false,
+		memoryMb: Number.isFinite(fromEnv) && fromEnv > 0 ? fromEnv : (settings.sandbox?.memoryMb ?? 64),
+		timeoutSeconds: settings.sandbox?.timeoutSeconds ?? 300,
+	};
+}
+
+export function resolveEnvironments(settings: CodemodeFeatureSettings): ResolvedEnvironments {
+	const environments = settings.environments;
+	return {
+		...(environments?.managedRoot === undefined ? {} : { managedRoot: environments.managedRoot }),
+		autoProvision: environments?.autoProvision ?? true,
+		jsInstaller: environments?.js?.installer ?? "auto",
+		pyInstaller: environments?.py?.installer ?? "pip",
+	};
+}
+
+export function resolveAdvertiseHelpers(settings: CodemodeFeatureSettings): boolean {
+	return settings.prompt?.advertiseHelpers ?? false;
+}
+
+export function resolveKernelToolsEnabled(settings: CodemodeFeatureSettings): boolean {
+	return settings.kernelTools?.enabled ?? true;
+}

package/src/config/memory-settings.ts

@@ -3,6 +3,9 @@ import { type Static, Type } from "typebox";
 import type { KernelMemoryThresholds } from "../bridge/memory-protocol.ts";
 import type { CodemodeSettings, Environment } from "./settings.ts";
 
+// The longest delay setTimeout honours (2^31 - 1 ms); a longer one fires after 1 ms.
+export const MAX_IDLE_PARK_MINUTES = 35_791;
+
 export const memorySettingsSchema = Type.Object(
 	{
 		gcWatermarkMb: Type.Optional(Type.Number({ minimum: 0 })),
@@ -10,6 +13,7 @@ export const memorySettingsSchema = Type.Object(
 		ceilingMb: Type.Optional(Type.Number({ minimum: 0 })),
 		retainedResultsMb: Type.Optional(Type.Number({ minimum: 0 })),
 		retainedImagesMb: Type.Optional(Type.Number({ minimum: 0 })),
+		idleParkMinutes: Type.Optional(Type.Number({ minimum: 0, maximum: MAX_IDLE_PARK_MINUTES })),
 	},
 	{ additionalProperties: false },
 );
@@ -27,6 +31,8 @@ export interface CodemodeMemorySettings {
 	readonly retainedResultsMb: number;
 	/** Disk budget (MiB) for settled-cell images spilled under the session artifacts dir; 0 keeps only the count cap. */
 	readonly retainedImagesMb: number;
+	/** Minutes with no cell running or queued before a kernel is closed and restarted on the next cell; absent or 0 never parks. */
+	readonly idleParkMinutes?: number;
 }
 
 export const DEFAULT_MEMORY_GC_WATERMARK_MB = 256;
@@ -67,6 +73,7 @@ export function mergeMemorySettings(input: CodemodeMemorySettingsInput | undefin
 		ceilingMb: input?.ceilingMb ?? defaults.ceilingMb,
 		retainedResultsMb: input?.retainedResultsMb ?? defaults.retainedResultsMb,
 		retainedImagesMb: input?.retainedImagesMb ?? defaults.retainedImagesMb,
+		...(input?.idleParkMinutes === undefined ? {} : { idleParkMinutes: input.idleParkMinutes }),
 	};
 }
 
@@ -91,6 +98,7 @@ export function validatedMemorySettings(input: CodemodeMemorySettingsInput | und
 			...defaults,
 			retainedResultsMb: merged.retainedResultsMb,
 			retainedImagesMb: merged.retainedImagesMb,
+			...(merged.idleParkMinutes === undefined ? {} : { idleParkMinutes: merged.idleParkMinutes }),
 		},
 		warnings: [warning],
 	};

package/src/config/settings-constants.ts

@@ -0,0 +1,7 @@
+export const HARD_LIMIT_ENVIRONMENT_FLAG = "SENPI_CODEMODE_HARD_LIMIT_SECONDS";
+export const FOREGROUND_WINDOW_ENVIRONMENT_FLAG = "SENPI_CODEMODE_FOREGROUND_SECONDS";
+export const RUN_BUDGET_ENVIRONMENT_FLAG = "SENPI_CODEMODE_RUN_BUDGET_SECONDS";
+export const MAX_DETACHED_CELLS_ENVIRONMENT_FLAG = "SENPI_CODEMODE_MAX_DETACHED_CELLS";
+export const DEFAULT_MAX_DETACHED_CELLS = 15;
+
+export type Environment = Readonly<Record<string, string | undefined>>;

package/src/config/settings-overrides.ts

@@ -0,0 +1,72 @@
+import type { CodemodeSettings } from "./settings.ts";
+import {
+	DEFAULT_MAX_DETACHED_CELLS,
+	type Environment,
+	FOREGROUND_WINDOW_ENVIRONMENT_FLAG,
+	HARD_LIMIT_ENVIRONMENT_FLAG,
+	MAX_DETACHED_CELLS_ENVIRONMENT_FLAG,
+	RUN_BUDGET_ENVIRONMENT_FLAG,
+} from "./settings-constants.ts";
+
+const languageEnvironmentFlags = {
+	py: "SENPI_CODEMODE_PY",
+	js: "SENPI_CODEMODE_JS",
+	rb: "SENPI_CODEMODE_RB",
+	jl: "SENPI_CODEMODE_JL",
+} as const;
+
+export function resolveEnabledLanguages(
+	settings: CodemodeSettings,
+	env: Environment = process.env,
+): CodemodeSettings["languages"] {
+	return {
+		py: resolveLanguage(settings.languages.py, env[languageEnvironmentFlags.py]),
+		js: resolveLanguage(settings.languages.js, env[languageEnvironmentFlags.js]),
+		rb: resolveLanguage(settings.languages.rb, env[languageEnvironmentFlags.rb]),
+		jl: resolveLanguage(settings.languages.jl, env[languageEnvironmentFlags.jl]),
+	};
+}
+
+/** Environment override wins over the settings file; a non-positive or malformed value is ignored. */
+export function resolveHardLimitSeconds(settings: CodemodeSettings, env: Environment = process.env): number {
+	return positiveSecondsOverride(env[HARD_LIMIT_ENVIRONMENT_FLAG]) ?? settings.hardLimitSeconds;
+}
+
+/** Environment override wins over the settings file; a non-positive or malformed value is ignored. */
+export function resolveForegroundWindowSeconds(settings: CodemodeSettings, env: Environment = process.env): number {
+	return positiveSecondsOverride(env[FOREGROUND_WINDOW_ENVIRONMENT_FLAG]) ?? settings.foregroundWindowSeconds;
+}
+
+/** Environment override wins over the settings file; a non-positive or malformed value is ignored. */
+export function resolveRunBudgetSeconds(settings: CodemodeSettings, env: Environment = process.env): number {
+	return positiveSecondsOverride(env[RUN_BUDGET_ENVIRONMENT_FLAG]) ?? settings.runBudgetSeconds;
+}
+
+/** Uses the same positive-integer environment parsing as the run budget. */
+export function resolveMaxDetachedCells(settings: CodemodeSettings, env: Environment = process.env): number {
+	return (
+		positiveSecondsOverride(env[MAX_DETACHED_CELLS_ENVIRONMENT_FLAG]) ??
+		settings.maxDetachedCells ??
+		DEFAULT_MAX_DETACHED_CELLS
+	);
+}
+
+function positiveSecondsOverride(value: string | undefined): number | undefined {
+	if (value === undefined) return undefined;
+	const parsed = Number.parseInt(value, 10);
+	return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+
+function resolveLanguage(fileSetting: boolean, environmentValue: string | undefined): boolean {
+	if (environmentValue === undefined) return fileSetting;
+	switch (environmentValue.trim().toLowerCase()) {
+		case "0":
+		case "false":
+			return false;
+		case "1":
+		case "true":
+			return true;
+		default:
+			return fileSetting;
+	}
+}

package/src/config/settings.ts

@@ -4,7 +4,10 @@ import { join } from "node:path";
 import type { Static } from "typebox";
 import { Type } from "typebox";
 import { Check } from "typebox/value";
+import { type CodemodeFeatureSettings, featureSettingsProperties, pickFeatureSettings } from "./feature-settings.ts";
 import { type CodemodeMemorySettings, memorySettingsSchema, validatedMemorySettings } from "./memory-settings.ts";
+import { DEFAULT_MAX_DETACHED_CELLS } from "./settings-constants.ts";
+import { withoutUnknownTopLevelKeys } from "./unknown-settings.ts";
 
 export const codemodeSettingsSchema = Type.Object(
 	{
@@ -15,6 +18,7 @@ export const codemodeSettingsSchema = Type.Object(
 					js: Type.Optional(Type.Boolean()),
 					rb: Type.Optional(Type.Boolean()),
 					jl: Type.Optional(Type.Boolean()),
+					pyInterpreter: Type.Optional(Type.String({ minLength: 1 })),
 				},
 				{ additionalProperties: false },
 			),
@@ -45,6 +49,7 @@ export const codemodeSettingsSchema = Type.Object(
 		),
 		statusEvents: Type.Optional(Type.Boolean()),
 		memory: Type.Optional(memorySettingsSchema),
+		...featureSettingsProperties,
 	},
 	{ additionalProperties: false },
 );
@@ -61,12 +66,14 @@ export interface CodemodeOutputSink {
 	readonly maxColumns: number;
 }
 
-export interface CodemodeSettings {
+export interface CodemodeSettings extends CodemodeFeatureSettings {
 	readonly languages: {
 		readonly py: boolean;
 		readonly js: boolean;
 		readonly rb: boolean;
 		readonly jl: boolean;
+		/** Explicit Python interpreter; unset keeps today's PATH detection. */
+		readonly pyInterpreter?: string;
 	};
 	/** Idle time an interactive call blocks the turn before the cell detaches; capped by the foreground window. */
 	readonly cellTimeoutSeconds: number;
@@ -118,8 +125,6 @@ export interface LoadedCodemodeSettings {
  */
 export const DEFAULT_HARD_LIMIT_SECONDS = 1800;
 
-export const HARD_LIMIT_ENVIRONMENT_FLAG = "SENPI_CODEMODE_HARD_LIMIT_SECONDS";
-
 /**
  * Bash parity: `terminal/tools/foreground-window.ts` auto-detaches a still-running bash command to a
  * background session at 60s regardless of its `timeout` kill deadline. An eval cell gets the same
@@ -128,8 +133,6 @@ export const HARD_LIMIT_ENVIRONMENT_FLAG = "SENPI_CODEMODE_HARD_LIMIT_SECONDS";
  */
 export const DEFAULT_FOREGROUND_WINDOW_SECONDS = 60;
 
-export const FOREGROUND_WINDOW_ENVIRONMENT_FLAG = "SENPI_CODEMODE_FOREGROUND_SECONDS";
-
 /**
  * One language kernel runs one cell at a time and a killed JavaScript cell that cannot settle
  * cooperatively restarts its worker, so a runaway cell costs far more than a runaway bash command:
@@ -137,11 +140,6 @@ export const FOREGROUND_WINDOW_ENVIRONMENT_FLAG = "SENPI_CODEMODE_FOREGROUND_SEC
  */
 export const DEFAULT_RUN_BUDGET_SECONDS = 300;
 
-export const DEFAULT_MAX_DETACHED_CELLS = 15;
-
-export const RUN_BUDGET_ENVIRONMENT_FLAG = "SENPI_CODEMODE_RUN_BUDGET_SECONDS";
-export const MAX_DETACHED_CELLS_ENVIRONMENT_FLAG = "SENPI_CODEMODE_MAX_DETACHED_CELLS";
-
 // OMP settings-schema.ts:3211-3299 has language/path settings only; eval.ts:427
 // defaults timeout to 30s, and codemode pins concurrency-bridge.ts:30 width to 4.
 export const defaultCodemodeSettings: ResolvedCodemodeSettings = {
@@ -169,15 +167,6 @@ export const defaultCodemodeSettings: ResolvedCodemodeSettings = {
 	memory: validatedMemorySettings(undefined).settings,
 };
 
-const languageEnvironmentFlags = {
-	py: "SENPI_CODEMODE_PY",
-	js: "SENPI_CODEMODE_JS",
-	rb: "SENPI_CODEMODE_RB",
-	jl: "SENPI_CODEMODE_JL",
-} as const;
-
-export type Environment = Readonly<Record<string, string | undefined>>;
-
 export async function loadCodemodeSettings(options: LoadCodemodeSettingsOptions = {}): Promise<LoadedCodemodeSettings> {
 	const cwd = options.cwd ?? process.cwd();
 	const homeDir = options.homeDir ?? homedir();
@@ -193,48 +182,6 @@ export async function loadCodemodeSettings(options: LoadCodemodeSettingsOptions
 	return { settings: defaultCodemodeSettings, source: null, warnings: [] };
 }
 
-export function resolveEnabledLanguages(
-	settings: CodemodeSettings,
-	env: Environment = process.env,
-): CodemodeSettings["languages"] {
-	return {
-		py: resolveLanguage(settings.languages.py, env[languageEnvironmentFlags.py]),
-		js: resolveLanguage(settings.languages.js, env[languageEnvironmentFlags.js]),
-		rb: resolveLanguage(settings.languages.rb, env[languageEnvironmentFlags.rb]),
-		jl: resolveLanguage(settings.languages.jl, env[languageEnvironmentFlags.jl]),
-	};
-}
-
-/** Environment override wins over the settings file; a non-positive or malformed value is ignored. */
-export function resolveHardLimitSeconds(settings: CodemodeSettings, env: Environment = process.env): number {
-	return positiveSecondsOverride(env[HARD_LIMIT_ENVIRONMENT_FLAG]) ?? settings.hardLimitSeconds;
-}
-
-/** Environment override wins over the settings file; a non-positive or malformed value is ignored. */
-export function resolveForegroundWindowSeconds(settings: CodemodeSettings, env: Environment = process.env): number {
-	return positiveSecondsOverride(env[FOREGROUND_WINDOW_ENVIRONMENT_FLAG]) ?? settings.foregroundWindowSeconds;
-}
-
-/** Environment override wins over the settings file; a non-positive or malformed value is ignored. */
-export function resolveRunBudgetSeconds(settings: CodemodeSettings, env: Environment = process.env): number {
-	return positiveSecondsOverride(env[RUN_BUDGET_ENVIRONMENT_FLAG]) ?? settings.runBudgetSeconds;
-}
-
-/** Uses the same positive-integer environment parsing as the run budget. */
-export function resolveMaxDetachedCells(settings: CodemodeSettings, env: Environment = process.env): number {
-	return (
-		positiveSecondsOverride(env[MAX_DETACHED_CELLS_ENVIRONMENT_FLAG]) ??
-		settings.maxDetachedCells ??
-		DEFAULT_MAX_DETACHED_CELLS
-	);
-}
-
-function positiveSecondsOverride(value: string | undefined): number | undefined {
-	if (value === undefined) return undefined;
-	const parsed = Number.parseInt(value, 10);
-	return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
-}
-
 async function loadSettingsFile(path: string): Promise<LoadedCodemodeSettings> {
 	const raw = await readFile(path, "utf8");
 	let parsed: unknown;
@@ -249,15 +196,21 @@ async function loadSettingsFile(path: string): Promise<LoadedCodemodeSettings> {
 		};
 	}
 
-	if (!Check(codemodeSettingsSchema, parsed)) {
+	const known = withoutUnknownTopLevelKeys(parsed, new Set(Object.keys(codemodeSettingsSchema.properties)), path);
+	const candidate = known.value;
+	if (!Check(codemodeSettingsSchema, candidate)) {
 		return {
 			settings: defaultCodemodeSettings,
 			source: path,
-			warnings: [`Invalid codemode settings in ${path}. Falling back to codemode defaults.`],
+			warnings: [...known.warnings, `Invalid codemode settings in ${path}. Falling back to codemode defaults.`],
 		};
 	}
 
-	return { settings: mergeSettings(parsed), source: path, warnings: validatedMemorySettings(parsed.memory).warnings };
+	return {
+		settings: mergeSettings(candidate),
+		source: path,
+		warnings: [...known.warnings, ...validatedMemorySettings(candidate.memory).warnings],
+	};
 }
 
 function mergeSettings(input: CodemodeSettingsInput): ResolvedCodemodeSettings {
@@ -267,6 +220,7 @@ function mergeSettings(input: CodemodeSettingsInput): ResolvedCodemodeSettings {
 			js: input.languages?.js ?? defaultCodemodeSettings.languages.js,
 			rb: input.languages?.rb ?? defaultCodemodeSettings.languages.rb,
 			jl: input.languages?.jl ?? defaultCodemodeSettings.languages.jl,
+			...(input.languages?.pyInterpreter === undefined ? {} : { pyInterpreter: input.languages.pyInterpreter }),
 		},
 		cellTimeoutSeconds: input.cellTimeoutSeconds ?? defaultCodemodeSettings.cellTimeoutSeconds,
 		foregroundWindowSeconds: input.foregroundWindowSeconds ?? defaultCodemodeSettings.foregroundWindowSeconds,
@@ -284,23 +238,10 @@ function mergeSettings(input: CodemodeSettingsInput): ResolvedCodemodeSettings {
 		},
 		statusEvents: input.statusEvents ?? defaultCodemodeSettings.statusEvents,
 		memory: validatedMemorySettings(input.memory).settings,
+		...pickFeatureSettings(input),
 	};
 }
 
-function resolveLanguage(fileSetting: boolean, environmentValue: string | undefined): boolean {
-	if (environmentValue === undefined) return fileSetting;
-	switch (environmentValue.trim().toLowerCase()) {
-		case "0":
-		case "false":
-			return false;
-		case "1":
-		case "true":
-			return true;
-		default:
-			return fileSetting;
-	}
-}
-
 async function fileExists(path: string): Promise<boolean> {
 	try {
 		await access(path);
@@ -309,3 +250,19 @@ async function fileExists(path: string): Promise<boolean> {
 		return false;
 	}
 }
+
+export {
+	DEFAULT_MAX_DETACHED_CELLS,
+	type Environment,
+	FOREGROUND_WINDOW_ENVIRONMENT_FLAG,
+	HARD_LIMIT_ENVIRONMENT_FLAG,
+	MAX_DETACHED_CELLS_ENVIRONMENT_FLAG,
+	RUN_BUDGET_ENVIRONMENT_FLAG,
+} from "./settings-constants.ts";
+export {
+	resolveEnabledLanguages,
+	resolveForegroundWindowSeconds,
+	resolveHardLimitSeconds,
+	resolveMaxDetachedCells,
+	resolveRunBudgetSeconds,
+} from "./settings-overrides.ts";

package/src/config/unknown-settings.ts

@@ -0,0 +1,19 @@
+/**
+ * A settings file written for a newer senpi may name keys this version does not know: they are dropped with
+ * one warning each instead of failing the whole file, so the user's other settings still apply. Only the
+ * top level is lenient; the known nested objects keep their strict schemas.
+ */
+export function withoutUnknownTopLevelKeys(
+	parsed: unknown,
+	known: ReadonlySet<string>,
+	path: string,
+): { readonly value: unknown; readonly warnings: string[] } {
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return { value: parsed, warnings: [] };
+	const kept: Record<string, unknown> = {};
+	const warnings: string[] = [];
+	for (const [key, value] of Object.entries(parsed)) {
+		if (known.has(key)) kept[key] = value;
+		else warnings.push(`Unknown codemode setting "${key}" in ${path} is ignored; the other settings still apply.`);
+	}
+	return { value: kept, warnings };
+}

package/src/extension/bridge-tool-call.ts

@@ -0,0 +1,37 @@
+import { isReservedToolName, runReservedTool } from "../bridges/reserved-dispatch.ts";
+import { defaultCodemodeSettings } from "../config/settings.ts";
+import { marshalToolResult } from "../tool/image.ts";
+import type { CreateCodemodeSessionManagerOptions } from "./session-manager-contract.ts";
+
+export interface BridgeToolCallRequest {
+	readonly toolName: string;
+	readonly args: unknown;
+	readonly callId: string;
+	readonly signal: AbortSignal;
+}
+
+// Subprocess kernels (py/rb/jl) reach the host only through this route, so every reply
+// must match the in-process JS path in tool/cell-handler.ts: reserved helper names dispatch
+// through runReservedTool (forwarding them made agent() fail with "Unknown tool __agent__"),
+// and ordinary tool results are marshalled to { text, images, details, hasError } — the raw
+// { content } shape left python cells unable to reach tool.read image blocks.
+export async function routeBridgeToolCall(
+	options: Pick<CreateCodemodeSessionManagerOptions, "executeTool" | "listTools" | "settings">,
+	request: BridgeToolCallRequest,
+): Promise<unknown> {
+	if (!isReservedToolName(request.toolName)) {
+		return marshalToolResult(await options.executeTool(request.toolName, request.args, { signal: request.signal }));
+	}
+	const taskTools = options.settings.taskTools ?? defaultCodemodeSettings.taskTools;
+	return await runReservedTool(request.toolName, {
+		callId: request.callId,
+		args: request.args,
+		executeTool: options.executeTool,
+		taskToolName: taskTools.task,
+		taskOutputToolName: taskTools.output,
+		listTools: options.listTools,
+		signal: request.signal,
+		emitStatus: () => {},
+		marshalToolResult,
+	});
+}