@oh-my-pi/pi-coding-agent 16.0.4 → 16.0.6

package/src/eval/js/context-manager.ts

@@ -44,6 +44,8 @@ interface PendingRun {
 
 interface JsSession {
 	sessionKey: string;
+	sessionId: string;
+	cwd: string;
 	worker: WorkerHandle;
 	state: "alive" | "dead";
 	pending: Map<string, PendingRun>;
@@ -151,7 +153,14 @@ export async function disposeAllVmContexts(): Promise<void> {
  */
 export async function smokeTestJsEvalWorker(): Promise<void> {
 	const worker = spawnJsWorker();
-	const session: JsSession = { sessionKey: "smoke", worker, state: "alive", pending: new Map() };
+	const session: JsSession = {
+		sessionKey: "smoke",
+		sessionId: "smoke",
+		cwd: process.cwd(),
+		worker,
+		state: "alive",
+		pending: new Map(),
+	};
 	try {
 		await initWorker(session, { cwd: process.cwd(), sessionId: "smoke" }, WORKER_INIT_TIMEOUT_MS);
 		if (worker.mode !== "worker") {
@@ -219,7 +228,11 @@ async function runOnce(
 
 async function acquireSession(sessionKey: string, snapshot: SessionSnapshot, timeoutMs?: number): Promise<JsSession> {
 	const existing = sessions.get(sessionKey);
-	if (existing && existing.state === "alive") return existing;
+	if (existing && existing.state === "alive") {
+		existing.sessionId = snapshot.sessionId;
+		existing.cwd = snapshot.cwd;
+		return existing;
+	}
 	const starting = startingSessions.get(sessionKey);
 	if (starting) return await starting;
 
@@ -231,6 +244,8 @@ async function acquireSession(sessionKey: string, snapshot: SessionSnapshot, tim
 		const worker = spawnJsWorker();
 		const session: JsSession = {
 			sessionKey,
+			sessionId: snapshot.sessionId,
+			cwd: snapshot.cwd,
 			worker,
 			state: "alive",
 			pending: new Map(),

package/src/eval/js/index.ts

@@ -9,7 +9,7 @@ import { executeJs } from "./executor";
 
 const JS_SESSION_PREFIX = "js:";
 
-function namespaceSessionId(sessionId: string): string {
+export function namespaceSessionId(sessionId: string): string {
 	return sessionId.startsWith(JS_SESSION_PREFIX) ? sessionId : `${JS_SESSION_PREFIX}${sessionId}`;
 }
 

package/src/eval/py/executor.ts

@@ -632,7 +632,7 @@ async function executePerCall(code: string, cwd: string, options: PythonExecutor
 	}
 	const kernel = await startKernel(cwd, options);
 	try {
-		return await executeWithKernel(kernel, code, { ...options, cwd: undefined });
+		return await executeWithKernel(kernel, code, { ...options, cwd });
 	} finally {
 		await kernel.shutdown().catch(() => undefined);
 	}
@@ -682,7 +682,7 @@ async function executeOnSession(code: string, cwd: string, options: PythonExecut
 			throw new PythonExecutionCancelledError(false);
 		}
 	}
-	const runOptions = { ...options, cwd: undefined };
+	const runOptions = { ...options, cwd };
 	try {
 		return await executeWithKernel(session.kernel, code, runOptions);
 	} catch (err) {

package/src/eval/py/runner.py

@@ -190,6 +190,11 @@ class _RunnerState:
 
 
 _CURRENT_RID: contextvars.ContextVar[str | None] = contextvars.ContextVar("omp_current_rid", default=None)
+_CURRENT_DISPLAYED_MATPLOTLIB_FIGURE_IDS: contextvars.ContextVar[set[int] | None] = contextvars.ContextVar(
+    "omp_displayed_matplotlib_figure_ids",
+    default=None,
+)
+
 
 _STATE = _RunnerState()
 
@@ -670,6 +675,36 @@ _REPR_MIMES = [
 ]
 
 
+def _is_matplotlib_figure(value: Any) -> bool:
+    figure_module = sys.modules.get("matplotlib.figure")
+    figure_cls = getattr(figure_module, "Figure", None)
+    if isinstance(figure_cls, type) and isinstance(value, figure_cls):
+        return True
+
+    value_type = type(value)
+    return value_type.__module__ == "matplotlib.figure" and value_type.__name__ == "Figure"
+
+
+def _matplotlib_figure_png(value: Any) -> str | None:
+    if not _is_matplotlib_figure(value):
+        return None
+
+    savefig = getattr(value, "savefig", None)
+    if not callable(savefig):
+        return None
+
+    try:
+        buf = io.BytesIO()
+        savefig(buf, format="png", bbox_inches="tight")
+    except Exception:
+        return None
+
+    displayed_ids = _CURRENT_DISPLAYED_MATPLOTLIB_FIGURE_IDS.get()
+    if displayed_ids is not None:
+        displayed_ids.add(id(value))
+    return base64.b64encode(buf.getvalue()).decode("ascii")
+
+
 def _coerce_image_bytes(value: Any) -> str:
     if isinstance(value, (bytes, bytearray)):
         return base64.b64encode(bytes(value)).decode("ascii")
@@ -685,6 +720,10 @@ def _mime_bundle(value: Any) -> dict:
     accessors, and always provides ``text/plain``.
     """
     bundle: dict[str, Any] = {}
+    matplotlib_png = _matplotlib_figure_png(value)
+    if matplotlib_png is not None:
+        bundle["image/png"] = matplotlib_png
+
 
     mimebundle = getattr(value, "_repr_mimebundle_", None)
     if callable(mimebundle):
@@ -758,6 +797,9 @@ def _flush_matplotlib_figures() -> None:
     for num in fignums:
         try:
             fig = plt.figure(num)
+            if id(fig) in (_CURRENT_DISPLAYED_MATPLOTLIB_FIGURE_IDS.get() or set()):
+                plt.close(fig)
+                continue
             buf = io.BytesIO()
             fig.savefig(buf, format="png", bbox_inches="tight")
             data = base64.b64encode(buf.getvalue()).decode("ascii")
@@ -978,6 +1020,7 @@ def _start_parent_watchdog() -> None:
 async def _handle_request_async(req: dict) -> None:
     rid = str(req.get("id"))
     token = _CURRENT_RID.set(rid)
+    displayed_matplotlib_token = _CURRENT_DISPLAYED_MATPLOTLIB_FIGURE_IDS.set(set())
     _STATE.capture_rid = rid
     _STATE.user_ns["__omp_run_id__"] = rid
     _STATE.cancel_requested = False
@@ -1046,6 +1089,7 @@ async def _handle_request_async(req: dict) -> None:
             _STATE.capture_rid = None
         _flush_stream_proxies(rid)
         _CURRENT_RID.reset(token)
+        _CURRENT_DISPLAYED_MATPLOTLIB_FIGURE_IDS.reset(displayed_matplotlib_token)
 
 
 def _emit_error(rid: str, exc: BaseException) -> None:

package/src/extensibility/custom-commands/loader.ts

@@ -1,13 +1,14 @@
 /**
  * Custom command loader - loads TypeScript command modules using native Bun import.
  *
- * Dependencies (the zod-backed typebox shim and pi-coding-agent) are injected via the
+ * Dependencies (the arktype validation and pi-coding-agent) are injected via the
  * CustomCommandAPI to avoid import resolution issues with custom commands loaded from user directories.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { getAgentDir, getProjectDir, isEnoent, logger } from "@oh-my-pi/pi-utils";
-import { z as zod } from "zod/v4";
+import * as arktype from "arktype";
+import * as zodModule from "zod/v4";
 import { getConfigDirs } from "../../config";
 import { execCommand } from "../../exec/exec";
 // Runtime self-reference: dereference this namespace only inside loader functions to keep the index.ts cycle safe.
@@ -186,7 +187,8 @@ export async function loadCustomCommands(options: LoadCustomCommandsOptions = {}
 		exec: (command: string, args: string[], execOptions) =>
 			execCommand(command, args, execOptions?.cwd ?? cwd, execOptions),
 		typebox,
-		zod,
+		arktype,
+		zod: zodModule,
 		pi: PiCodingAgent,
 	};
 

package/src/extensibility/custom-commands/types.ts

@@ -5,7 +5,8 @@
  * Unlike markdown commands which expand to prompts, custom commands can execute
  * arbitrary logic with full access to the hook context.
  */
-import type { z } from "zod/v4";
+import type * as arktype from "arktype";
+import type * as zod from "zod/v4";
 import type { ExecOptions, ExecResult, HookCommandContext } from "../../extensibility/hooks/types";
 import type * as PiCodingAgent from "../../index";
 import type * as TypeBox from "../typebox";
@@ -24,8 +25,10 @@ export interface CustomCommandAPI {
 	exec(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
 	/** Injected zod-backed typebox shim (legacy/compat). */
 	typebox: typeof TypeBox;
-	/** Injected zod module for Zod-authored custom commands. */
-	zod: typeof z;
+	/** Injected arktype module for validation in custom commands. */
+	arktype: typeof arktype;
+	/** Injected zod/v4 module for canonical command validation. */
+	zod: typeof zod;
 	/** Injected pi-coding-agent exports */
 	pi: typeof PiCodingAgent;
 }

package/src/extensibility/custom-tools/loader.ts

@@ -7,7 +7,8 @@
 import * as path from "node:path";
 import type { AgentToolResult } from "@oh-my-pi/pi-agent-core";
 import { logger } from "@oh-my-pi/pi-utils";
-import { z } from "zod/v4";
+import { type } from "arktype";
+import * as zodModule from "zod/v4";
 import { toolCapability } from "../../capability/tool";
 import { type CustomTool, loadCapability } from "../../discovery";
 import type { ExecOptions } from "../../exec/exec";
@@ -108,7 +109,8 @@ export class CustomToolLoader {
 			hasUI: false,
 			logger,
 			typebox,
-			zod: z,
+			arktype: type,
+			zod: zodModule,
 			pi,
 			pushPendingAction: action => {
 				if (!pushPendingAction) {

package/src/extensibility/custom-tools/types.ts

@@ -15,7 +15,8 @@ import type { CompactionResult } from "@oh-my-pi/pi-agent-core/compaction";
 import type { FetchImpl, Model, Static, TSchema } from "@oh-my-pi/pi-ai";
 import type { Component } from "@oh-my-pi/pi-tui";
 import type { logger as PiLogger } from "@oh-my-pi/pi-utils";
-import type { z } from "zod/v4";
+import type { type as ArkType } from "arktype";
+import type * as zod from "zod/v4";
 import type { Rule } from "../../capability/rule";
 import type { ModelRegistry } from "../../config/model-registry";
 import type { Settings } from "../../config/settings";
@@ -61,10 +62,12 @@ export interface CustomToolAPI {
 	hasUI: boolean;
 	/** File logger for error/warning/debug messages */
 	logger: typeof PiLogger;
-	/** Injected zod-backed typebox shim (legacy/compat — Zod-authored tools are preferred). */
+	/** Injected typebox shim (legacy/compat — arktype-authored tools are preferred). */
 	typebox: typeof TypeBox;
-	/** Injected zod module for Zod-authored custom tools. */
-	zod: typeof z;
+	/** Injected arktype module for arktype-authored custom tools. */
+	arktype: typeof ArkType;
+	/** Injected zod/v4 module for canonical parameter schemas. */
+	zod: typeof zod;
 	/** Injected pi-coding-agent exports */
 	pi: typeof PiCodingAgent;
 	/** Push a preview action that can later be resolved with the hidden resolve tool */
@@ -195,7 +198,7 @@ export interface CustomTool<TParams extends TSchema = TSchema, TDetails = any> {
 	strict?: boolean;
 	/** Description for LLM */
 	description: string;
-	/** Parameter schema (Zod or TypeBox; TypeBox is auto-lifted to Zod at registration). */
+	/** Parameter schema (arktype, TypeBox, or legacy formats). */
 	parameters: TParams;
 	/** If true, tool is excluded unless explicitly listed in --tools or agent's tools field */
 	hidden?: boolean;

package/src/extensibility/extensions/loader.ts

@@ -8,7 +8,8 @@ import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
 import type { ImageContent, Model, TextContent, TSchema } from "@oh-my-pi/pi-ai";
 import type { KeyId } from "@oh-my-pi/pi-tui";
 import { hasFsCode, isEacces, isEnoent, logger } from "@oh-my-pi/pi-utils";
-import { z } from "zod/v4";
+import { Type } from "arktype";
+import * as zodModule from "zod/v4";
 import { type ExtensionModule, extensionModuleCapability } from "../../capability/extension-module";
 import { type Hook, hookCapability } from "../../capability/hook";
 import { loadCapability } from "../../discovery";
@@ -123,7 +124,8 @@ export class ExtensionRuntime implements IExtensionRuntime {
 class ConcreteExtensionAPI implements ExtensionAPI, IExtensionRuntime {
 	readonly logger = logger;
 	readonly typebox = TypeBox;
-	readonly zod = z;
+	readonly arktype = Type;
+	readonly zod = zodModule;
 	readonly flagValues = new Map<string, boolean | string>();
 	readonly pendingProviderRegistrations: Array<{
 		name: string;

package/src/extensibility/extensions/runner.ts

@@ -46,6 +46,8 @@ import type {
 	SessionBeforeSwitchResult,
 	SessionBeforeTreeResult,
 	SessionCompactingResult,
+	SessionStopEvent,
+	SessionStopEventResult,
 	ToolCallEvent,
 	ToolCallEventResult,
 	ToolResultEvent,
@@ -135,7 +137,9 @@ type RunnerEmitResult<TEvent extends RunnerEmitEvent> = TEvent extends { type: "
 				? SessionBeforeTreeResult | undefined
 				: TEvent extends { type: "session.compacting" }
 					? SessionCompactingResult | undefined
-					: undefined;
+					: TEvent extends { type: "session_stop" }
+						? SessionStopEventResult | undefined
+						: undefined;
 
 export type NewSessionHandler = (options?: {
 	parentSession?: string;
@@ -322,6 +326,10 @@ export class ExtensionRunner {
 		await this.emit({ type: "credential_disabled", ...event });
 	}
 
+	async emitSessionStop(event: Omit<SessionStopEvent, "type">): Promise<SessionStopEventResult | undefined> {
+		return await this.emit({ type: "session_stop", ...event });
+	}
+
 	getUIContext(): ExtensionUIContext {
 		return this.#uiContext;
 	}
@@ -588,7 +596,7 @@ export class ExtensionRunner {
 
 	async emit<TEvent extends RunnerEmitEvent>(event: TEvent): Promise<RunnerEmitResult<TEvent>> {
 		const ctx = this.createContext();
-		let result: SessionBeforeEventResult | SessionCompactingResult | undefined;
+		let result: SessionBeforeEventResult | SessionCompactingResult | SessionStopEventResult | undefined;
 
 		if (this.#isSessionShutdownEvent(event)) {
 			const timeoutMs = handlerTimeoutForEvent(event.type);
@@ -627,6 +635,16 @@ export class ExtensionRunner {
 				if (event.type === "session.compacting" && handlerResult) {
 					result = handlerResult as SessionCompactingResult;
 				}
+
+				if (event.type === "session_stop" && handlerResult) {
+					result = handlerResult as SessionStopEventResult;
+					const hasContinuationContext =
+						(typeof result.additionalContext === "string" && result.additionalContext.length > 0) ||
+						(typeof result.reason === "string" && result.reason.length > 0);
+					if ((result.continue === true || result.decision === "block") && hasContinuationContext) {
+						return result as RunnerEmitResult<TEvent>;
+					}
+				}
 			}
 		}
 

package/src/extensibility/extensions/types.ts

@@ -32,7 +32,8 @@ import type {
 import type { OAuthCredentials, OAuthLoginCallbacks } from "@oh-my-pi/pi-ai/oauth/types";
 import type { AutocompleteItem, Component, EditorTheme, KeyId, TUI } from "@oh-my-pi/pi-tui";
 import type { logger as PiLogger } from "@oh-my-pi/pi-utils";
-import type { z } from "zod/v4";
+import type { Type as arktype } from "arktype";
+import type * as zod from "zod/v4";
 import type { KeybindingsManager } from "../../config/keybindings";
 import type { ModelRegistry } from "../../config/model-registry";
 import type { EditToolDetails } from "../../edit";
@@ -82,6 +83,8 @@ import type {
 	SessionEvent,
 	SessionShutdownEvent,
 	SessionStartEvent,
+	SessionStopEvent,
+	SessionStopEventResult,
 	SessionSwitchEvent,
 	SessionTreeEvent,
 	TodoReminderEvent,
@@ -274,11 +277,11 @@ export interface ExtensionUIContext {
 // ============================================================================
 
 export interface ContextUsage {
-	/** Estimated context tokens, or null if unknown (e.g. right after compaction, before next LLM response). */
-	tokens: number | null;
+	/** Estimated context tokens. */
+	tokens: number;
 	contextWindow: number;
-	/** Context usage as percentage of context window, or null if tokens is unknown. */
-	percent: number | null;
+	/** Context usage as percentage of context window. */
+	percent: number;
 }
 
 export interface CompactOptions {
@@ -525,7 +528,14 @@ export interface BeforeAgentStartEvent {
 	systemPrompt: string[];
 }
 
-export type { AgentEndEvent, AgentStartEvent, TurnEndEvent, TurnStartEvent } from "../shared-events";
+export type {
+	AgentEndEvent,
+	AgentStartEvent,
+	SessionStopEvent,
+	SessionStopEventResult,
+	TurnEndEvent,
+	TurnStartEvent,
+} from "../shared-events";
 
 /** Fired when a message starts (user, assistant, or toolResult) */
 export interface MessageStartEvent {
@@ -802,6 +812,7 @@ export type ExtensionEvent =
 	| BeforeAgentStartEvent
 	| AgentStartEvent
 	| AgentEndEvent
+	| SessionStopEvent
 	| TurnStartEvent
 	| TurnEndEvent
 	| MessageStartEvent
@@ -938,8 +949,10 @@ export interface ExtensionAPI {
 	/** Injected zod-backed typebox shim for legacy `Type.Object(...)` parameter authoring. */
 	typebox: typeof TypeBox;
 
-	/** Injected zod module for Zod-authored extension tools (canonical going forward). */
-	zod: typeof z;
+	/** Injected arktype module for arktype-authored extension tools (canonical going forward). */
+	arktype: typeof arktype;
+	/** Injected zod/v4 module for canonical extension tool parameter schemas. */
+	zod: typeof zod;
 
 	/** Injected pi-coding-agent exports for accessing SDK utilities */
 	pi: typeof PiCodingAgent;
@@ -978,6 +991,7 @@ export interface ExtensionAPI {
 	on(event: "before_agent_start", handler: ExtensionHandler<BeforeAgentStartEvent, BeforeAgentStartEventResult>): void;
 	on(event: "agent_start", handler: ExtensionHandler<AgentStartEvent>): void;
 	on(event: "agent_end", handler: ExtensionHandler<AgentEndEvent>): void;
+	on(event: "session_stop", handler: ExtensionHandler<SessionStopEvent, SessionStopEventResult>): void;
 	on(event: "turn_start", handler: ExtensionHandler<TurnStartEvent>): void;
 	on(event: "turn_end", handler: ExtensionHandler<TurnEndEvent>): void;
 	on(event: "message_start", handler: ExtensionHandler<MessageStartEvent>): void;

package/src/extensibility/hooks/loader.ts

@@ -3,7 +3,8 @@
  */
 import * as path from "node:path";
 import { logger } from "@oh-my-pi/pi-utils";
-import { z as zod } from "zod/v4";
+import * as arktype from "arktype";
+import * as zodModule from "zod/v4";
 import { hookCapability } from "../../capability/hook";
 import type { Hook } from "../../discovery";
 import { loadCapability } from "../../discovery";
@@ -139,7 +140,9 @@ async function createHookAPI(
 		},
 		logger,
 		typebox,
-		zod,
+		// HookAPI.arktype is typed as the arktype `Type` constructor; expose it from the module namespace.
+		arktype: arktype.Type,
+		zod: zodModule,
 		pi: PiCodingAgent,
 	} as HookAPI;
 

package/src/extensibility/hooks/types.ts

@@ -1,7 +1,8 @@
 import type { ImageContent, Message, Model, TextContent } from "@oh-my-pi/pi-ai";
 import type { Component, TUI } from "@oh-my-pi/pi-tui";
 import type { logger as PiLogger } from "@oh-my-pi/pi-utils";
-import type { z } from "zod/v4";
+import type { Type } from "arktype";
+import type * as zod from "zod/v4";
 import type { ModelRegistry } from "../../config/model-registry";
 import type { EditToolDetails } from "../../edit";
 import type { ExecOptions, ExecResult } from "../../exec/exec";
@@ -582,10 +583,12 @@ export interface HookAPI {
 
 	/** File logger for error/warning/debug messages */
 	logger: typeof PiLogger;
-	/** Injected zod-backed typebox shim (legacy/compat — prefer `zod`). */
+	/** Injected zod-backed typebox shim (legacy/compat — prefer `arktype`). */
 	typebox: typeof TypeBox;
-	/** Injected zod module for Zod-authored hooks. */
-	zod: typeof z;
+	/** Injected arktype module for arktype-authored hooks. */
+	arktype: typeof Type;
+	/** Injected zod/v4 module for canonical hook validation. */
+	zod: typeof zod;
 	/** Injected pi-coding-agent exports */
 	pi: typeof PiCodingAgent;
 }

package/src/extensibility/legacy-pi-ai-shim.ts

@@ -11,14 +11,51 @@
  * bare package root. Subpath imports (`@oh-my-pi/pi-ai/oauth`, etc.)
  * continue to resolve directly against the bundled pi-ai package.
  *
- * The `Type` runtime is borrowed from the Zod-backed TypeBox shim that
- * already serves bare `@sinclair/typebox` imports for the same extension
- * class, keeping the legacy-compat surface internally consistent.
+ * The `Type` runtime and legacy `StringEnum()` helper are borrowed from the
+ * Zod-backed TypeBox shim that already serves TypeBox imports for the same
+ * extension class, keeping the legacy-compat surface internally consistent.
  *
  * Type-level `Static` and `TSchema` continue to come from pi-ai's own
  * `types.ts` via the `export *` below — pi-ai still exports both as types,
- * only the runtime `Type` builder was removed.
+ * only the runtime `Type` builder and `StringEnum()` helper were removed.
  */
+import { type TSchema, Type } from "./typebox";
+
+export interface StringEnumOptions<T extends string> {
+	description?: string;
+	default?: T;
+	examples?: T[];
+	[key: string]: unknown;
+}
+
+function stringEnumWireSchema<T extends string>(values: readonly T[], options: StringEnumOptions<T> | undefined) {
+	const schema: Record<string, unknown> = {
+		type: "string",
+		enum: [...values],
+	};
+	if (!options) return schema;
+	for (const key in options) {
+		if (options[key] !== undefined) {
+			schema[key] = options[key];
+		}
+	}
+	return schema;
+}
+
+export function StringEnum<T extends string>(values: readonly T[], options?: StringEnumOptions<T>): TSchema {
+	const opts = {
+		description: options?.description ?? "Legacy string enum compatibility schema",
+		...options,
+	};
+	const schema: TSchema = values.length === 0 ? Type.Never(opts) : Type.Enum(values, opts);
+	Object.defineProperty(schema, "toJSON", {
+		value: () => stringEnumWireSchema(values, options),
+		enumerable: false,
+		writable: true,
+		configurable: true,
+	});
+	return schema;
+}
 
 export * from "@oh-my-pi/pi-ai";
-export { Type } from "./typebox";
+export { Type };

package/src/extensibility/legacy-pi-coding-agent-shim.ts

@@ -12,4 +12,117 @@
  * the same module identity as a direct `@oh-my-pi/pi-coding-agent` import.
  */
 
+import type { AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import type { TSchema } from "@oh-my-pi/pi-ai";
+import { parseFrontmatter as parseOmpFrontmatter } from "@oh-my-pi/pi-utils";
+import { Settings } from "../config/settings";
+import { BUILTIN_TOOLS, type Tool, type ToolSession } from "../tools";
+import type { ToolDefinition } from "./extensions/types";
+import { Type } from "./typebox";
+
+const TOOL_DEFINITION_MARKER = "__isToolDefinition";
+const LEGACY_BUILTIN_TOOL_MARKER = "__ompLegacyBuiltinTool";
+const LEGACY_CODING_TOOL_NAMES = ["read", "bash", "edit", "write"] as const;
+
+type LegacyCodingToolName = (typeof LEGACY_CODING_TOOL_NAMES)[number];
+type LegacyBuiltinToolDefinition = ToolDefinition & { [LEGACY_BUILTIN_TOOL_MARKER]: true };
+
+function markToolDefinition<TParams extends TSchema, TDetails>(
+	tool: ToolDefinition<TParams, TDetails>,
+): ToolDefinition<TParams, TDetails> {
+	Object.defineProperty(tool, TOOL_DEFINITION_MARKER, {
+		value: true,
+		enumerable: false,
+		writable: false,
+		configurable: true,
+	});
+	return tool;
+}
+function legacyToolSession(cwd: string): ToolSession {
+	return {
+		cwd,
+		hasUI: false,
+		getSessionFile: () => null,
+		getSessionSpawns: () => null,
+		settings: Settings.isolated(),
+	};
+}
+
+function createBuiltinTool(cwd: string, name: LegacyCodingToolName): Tool {
+	const tool = BUILTIN_TOOLS[name](legacyToolSession(cwd));
+	if (tool instanceof Promise) {
+		throw new Error(`Built-in ${name} tool factory unexpectedly returned a promise.`);
+	}
+	if (!tool) {
+		throw new Error(`Built-in ${name} tool is unavailable.`);
+	}
+	return tool;
+}
+
+async function executeBuiltinTool(
+	cwd: string,
+	name: LegacyCodingToolName,
+	toolCallId: string,
+	params: unknown,
+	signal: AbortSignal | undefined,
+	onUpdate: AgentToolUpdateCallback | undefined,
+) {
+	const tool = createBuiltinTool(cwd, name);
+	return tool.execute(toolCallId, params, signal, onUpdate);
+}
+
+function legacyBuiltinTool(cwd: string, name: LegacyCodingToolName): ToolDefinition {
+	const tool = createBuiltinTool(cwd, name);
+	const definition: LegacyBuiltinToolDefinition = {
+		name: tool.name,
+		label: tool.label,
+		description: tool.description,
+		parameters: tool.parameters,
+		hidden: tool.hidden,
+		deferrable: tool.deferrable,
+		approval: tool.approval,
+		execute: (toolCallId, params, signal, onUpdate) =>
+			executeBuiltinTool(cwd, name, toolCallId, params, signal, onUpdate),
+		[LEGACY_BUILTIN_TOOL_MARKER]: true,
+	};
+	return markToolDefinition(definition);
+}
+
+export interface ParsedFrontmatter<T extends Record<string, unknown> = Record<string, unknown>> {
+	frontmatter: T;
+	body: string;
+}
+
+export function parseFrontmatter<T extends Record<string, unknown> = Record<string, unknown>>(
+	content: string,
+): ParsedFrontmatter<T> {
+	const { frontmatter, body } = parseOmpFrontmatter(content, { level: "fatal" });
+	return { frontmatter: frontmatter as T, body };
+}
+
+export function stripFrontmatter(content: string): string {
+	return parseFrontmatter(content).body;
+}
+
+export function defineTool<TParams extends TSchema = TSchema, TDetails = unknown>(
+	tool: ToolDefinition<TParams, TDetails>,
+): ToolDefinition<TParams, TDetails> {
+	return markToolDefinition(tool);
+}
+
+export function createCodingTools(cwd: string): ToolDefinition[] {
+	return LEGACY_CODING_TOOL_NAMES.map(name => legacyBuiltinTool(cwd, name));
+}
+
+export const SettingsManager = {
+	create(cwd: string, agentDir?: string): Promise<Settings> {
+		return Settings.init({ cwd, agentDir });
+	},
+
+	inMemory(): Settings {
+		return Settings.isolated();
+	},
+} as const;
+
 export * from "../index";
+export { Type };