@code-yeongyu/senpi 2026.9.15-2 → 2026.9.16-2

package/node_modules/@code-yeongyu/senpi-codemode/src/bridge/kernel-tools-protocol.ts

@@ -0,0 +1,85 @@
+import { type Static, Type } from "typebox";
+
+const kernelToolErrorSchema = Type.Object({
+	message: Type.String(),
+	name: Type.Optional(Type.String()),
+	stack: Type.Optional(Type.String()),
+	code: Type.Optional(Type.String()),
+});
+
+export const kernelToolDescriptorSchema = Type.Object({
+	name: Type.String({ minLength: 1 }),
+	description: Type.String(),
+	input_schema: Type.Unknown(),
+	language: Type.Literal("js"),
+	kernel_generation: Type.Integer({ minimum: 0 }),
+	definition_revision: Type.Integer({ minimum: 1 }),
+});
+
+const describeResultSchema = Type.Union([
+	Type.Object({
+		name: Type.String({ minLength: 1 }),
+		ok: Type.Literal(true),
+		descriptor: kernelToolDescriptorSchema,
+	}),
+	Type.Object({
+		name: Type.String({ minLength: 1 }),
+		ok: Type.Literal(false),
+		error: kernelToolErrorSchema,
+	}),
+]);
+
+export const kernelToolHostToKernelSchemas = [
+	Type.Object({
+		type: Type.Literal("kernel-tool-describe"),
+		requestId: Type.String({ minLength: 1 }),
+		names: Type.Array(Type.String({ minLength: 1 })),
+	}),
+	Type.Object({
+		type: Type.Literal("kernel-tool-invoke"),
+		requestId: Type.String({ minLength: 1 }),
+		name: Type.String({ minLength: 1 }),
+		kernel_generation: Type.Integer({ minimum: 0 }),
+		definition_revision: Type.Integer({ minimum: 1 }),
+		args: Type.Unknown(),
+		call_id: Type.String({ minLength: 1 }),
+	}),
+	Type.Object({
+		type: Type.Literal("kernel-tool-cancel"),
+		requestId: Type.String({ minLength: 1 }),
+	}),
+	Type.Object({
+		type: Type.Literal("kernel-tools-names"),
+		hostToolNames: Type.Array(Type.String({ minLength: 1 })),
+		foreignLanguageNames: Type.Array(Type.String({ minLength: 1 })),
+	}),
+] as const;
+
+export const kernelToolKernelToHostSchemas = [
+	Type.Object({
+		type: Type.Literal("kernel-tool-describe-reply"),
+		requestId: Type.String({ minLength: 1 }),
+		ok: Type.Literal(true),
+		results: Type.Array(describeResultSchema),
+	}),
+	Type.Object({
+		type: Type.Literal("kernel-tool-describe-reply"),
+		requestId: Type.String({ minLength: 1 }),
+		ok: Type.Literal(false),
+		error: kernelToolErrorSchema,
+	}),
+	Type.Object({
+		type: Type.Literal("kernel-tool-invoke-reply"),
+		requestId: Type.String({ minLength: 1 }),
+		ok: Type.Literal(true),
+		value: Type.Unknown(),
+	}),
+	Type.Object({
+		type: Type.Literal("kernel-tool-invoke-reply"),
+		requestId: Type.String({ minLength: 1 }),
+		ok: Type.Literal(false),
+		error: kernelToolErrorSchema,
+	}),
+] as const;
+
+export type KernelToolDescriptorMessage = Static<typeof kernelToolDescriptorSchema>;

package/node_modules/@code-yeongyu/senpi-codemode/src/bridge/protocol.ts

@@ -1,6 +1,7 @@
 import { createHash, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 import { type Static, Type } from "typebox";
 import { Value } from "typebox/value";
+import { kernelToolHostToKernelSchemas, kernelToolKernelToHostSchemas } from "./kernel-tools-protocol.ts";
 
 export const BRIDGE_FRAME_MAX_BYTES = 10 * 1024 * 1024;
 
@@ -27,6 +28,9 @@ const hostToKernelMessageSchema = Type.Union([
 		sessionId: Type.String({ minLength: 1 }),
 		connection: connectionConfigSchema,
 		sessionEnv: Type.Optional(Type.Record(Type.String(), Type.String())),
+		kernelGeneration: Type.Optional(Type.Integer({ minimum: 1 })),
+		hostToolNames: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+		foreignLanguageNames: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
 	}),
 	Type.Object({
 		type: Type.Literal("run"),
@@ -53,6 +57,7 @@ const hostToKernelMessageSchema = Type.Union([
 	Type.Object({
 		type: Type.Literal("close"),
 	}),
+	...kernelToolHostToKernelSchemas,
 ]);
 
 const kernelToHostMessageSchema = Type.Union([
@@ -92,6 +97,7 @@ const kernelToHostMessageSchema = Type.Union([
 		durationMs: Type.Integer({ minimum: 0 }),
 	}),
 	Type.Object({ type: Type.Literal("closed") }),
+	...kernelToolKernelToHostSchemas,
 ]);
 
 const bridgeMessageSchema = Type.Union([hostToKernelMessageSchema, kernelToHostMessageSchema]);

package/node_modules/@code-yeongyu/senpi-codemode/src/bridges/agent-bridge.ts

@@ -11,6 +11,7 @@ const agentArgsSchema = Type.Object(
 		label: Type.Optional(Type.String()),
 		schema: Type.Optional(Type.Unknown()),
 		handle: Type.Optional(Type.Boolean()),
+		tools: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
 		isolated: Type.Optional(Type.Boolean()),
 		apply: Type.Optional(Type.Boolean()),
 		merge: Type.Optional(Type.Boolean()),
@@ -19,7 +20,19 @@ const agentArgsSchema = Type.Object(
 );
 
 const unsupportedIsolationWarning = "isolated/apply/merge unsupported (no isolation in task engine)";
-const taskIdPattern = /\bst_[A-Za-z0-9_-]+\b/;
+const taskHandleSchema = Type.Object(
+	{
+		task_id: Type.String({ pattern: "^st_[0-9a-f]+$" }),
+		run_epoch: Type.Integer({ minimum: 0 }),
+	},
+	{ additionalProperties: true },
+);
+
+/** Structural host contract; no orchestration package dependency. */
+export type TaskHandleDetails = {
+	readonly task_id: string;
+	readonly run_epoch: number;
+};
 const droppedOptionNames = ["isolated", "apply", "merge"] as const;
 
 type AgentArgs = Static<typeof agentArgsSchema>;
@@ -29,6 +42,7 @@ type TaskParams = {
 	readonly model?: string;
 	readonly name?: string;
 	readonly run_in_background: boolean;
+	readonly tools?: readonly string[];
 };
 type ProgressContext = { readonly fallbackId: string; readonly warning?: string };
 
@@ -48,7 +62,7 @@ export type EvalAgentResult =
 	| { readonly text: string }
 	| { readonly text: string; readonly data: unknown }
 	| { readonly text: string; readonly parseError: string }
-	| { readonly text: string; readonly id: string; readonly handle: string };
+	| { readonly text: string; readonly id: string; readonly handle: string; readonly run_epoch: number };
 
 class AgentArgumentsError extends Error {
 	readonly name = "AgentArgumentsError";
@@ -68,9 +82,10 @@ class AgentUnavailableError extends Error {
 
 class AgentHandleError extends Error {
 	readonly name = "AgentHandleError";
+	readonly code = "invalid_task_handle";
 
 	constructor() {
-		super("agent() background task result did not include a task id");
+		super("agent() requires successful task details with a valid task_id and nonnegative integer run_epoch");
 	}
 }
 
@@ -105,9 +120,8 @@ export async function runEvalAgent(args: unknown, options: RunEvalAgentOptions):
 
 	const text = resultText(result);
 	if (parsed.handle === true) {
-		const id = resultTaskId(result, text);
-		if (!id) throw new AgentHandleError();
-		return { text, id, handle: `agent://${id}` };
+		const { task_id: id, run_epoch } = resultTaskHandle(result);
+		return { text, id, handle: `agent://${id}`, run_epoch };
 	}
 	if (!structured) return { text };
 	return parseStructuredText(text);
@@ -130,6 +144,7 @@ function toTaskParams(args: AgentArgs, structured: boolean): TaskParams {
 		...(args.model === undefined ? {} : { model: args.model }),
 		...(args.label === undefined ? {} : { name: args.label }),
 		run_in_background: args.handle === true,
+		...(args.tools === undefined ? {} : { tools: args.tools }),
 	};
 }
 
@@ -168,11 +183,15 @@ function resultText(result: AgentToolResult<unknown>): string {
 		.join("\n");
 }
 
-function resultTaskId(result: AgentToolResult<unknown>, text: string): string | undefined {
-	const details = isRecord(result.details) ? result.details : undefined;
-	const detailId = firstString(details, ["task_id", "taskId", "id"]);
-	if (detailId) return detailId;
-	return text.match(taskIdPattern)?.[0];
+function resultTaskHandle(result: AgentToolResult<unknown>): TaskHandleDetails {
+	const details = result.details;
+	if (
+		("isError" in result && result.isError === true) ||
+		(isRecord(details) && (details.isError === true || details.error !== undefined)) ||
+		!Check(taskHandleSchema, details)
+	)
+		throw new AgentHandleError();
+	return details;
 }
 
 function firstString(

package/node_modules/@code-yeongyu/senpi-codemode/src/extension/session-manager.ts

@@ -215,6 +215,8 @@ class DefaultCodemodeSessionManager implements CodemodeSessionManager {
 				cwd: this.#options.cwd,
 				parallelPoolWidth,
 				onMessage,
+				hostToolNames: () => this.#options.listTools?.().map((tool) => tool.name) ?? [],
+				foreignLanguageNames: () => this.#foreignKernelToolNames(),
 				...(this.#options.sessionEnv ? { sessionEnv: this.#options.sessionEnv } : {}),
 				...(localRoots ? { localRoots: { ...localRoots } } : {}),
 				...(this.#options.artifactsDir ? { artifactsDir: this.#options.artifactsDir } : {}),
@@ -259,6 +261,15 @@ class DefaultCodemodeSessionManager implements CodemodeSessionManager {
 		});
 	}
 
+	#foreignKernelToolNames(): string[] {
+		const names: string[] = [];
+		for (const [language, kernel] of this.#kernels) {
+			if (language === "js") continue;
+			names.push(...(kernel.listKernelToolNames?.() ?? []));
+		}
+		return names;
+	}
+
 	#contextFor(signal: AbortSignal): ExtensionContext {
 		const ctx = this.#context;
 		if (!ctx) throw new CodemodeContextUnavailableError();

package/node_modules/@code-yeongyu/senpi-codemode/src/index.ts

@@ -23,6 +23,7 @@ import type { CodemodeSessionManager, CreateCodemodeSessionManagerOptions } from
 import { SessionManagerProxy } from "./extension/session-manager-proxy.ts";
 import { activeBunSkillPath, registerBunSkillContribution } from "./extension/skill-contribution.ts";
 import { WAKE_SOURCE_STATE_EVENT, type WakeSourceState } from "./extension/wake-source-state.ts";
+import type { KernelToolsCapability } from "./kernels/js/kernel-tools-types.ts";
 import { EvalDetachedCellManager, type EvalDetachedCellStatusEntry } from "./tool/detached-cell-manager.ts";
 import {
 	EVAL_EXECUTION_EVENT,
@@ -48,6 +49,8 @@ export interface CodemodeExtensionAPI {
 	registerRemovedToolHint(name: string, hint: string): void;
 	on(event: CodemodeEvent | "resources_discover", handler: (event: unknown, ctx: ExtensionContext) => unknown): void;
 	executeTool: AgentExecuteTool;
+	/** Present only while a live JavaScript eval owns the host-tool context. */
+	kernelTools?: KernelToolsCapability;
 	getActiveTools(): string[];
 	getAllTools(): readonly EvalSchemaToolInfo[];
 	sendMessage(
@@ -259,4 +262,11 @@ function modelIdFrom(event: unknown): string | undefined {
 	return typeof model.id === "string" ? model.id : undefined;
 }
 
+export {
+	KERNEL_TOOLS_UNSUPPORTED,
+	type KernelToolDescriptor,
+	type KernelToolsCapability,
+	type KernelToolsDescribeResult,
+	type KernelToolsInvokeRequest,
+} from "./kernels/js/kernel-tools-types.ts";
 export { enabledLanguagesFrom };

package/node_modules/@code-yeongyu/senpi-codemode/src/kernels/jl/prelude.jl

@@ -181,6 +181,51 @@ end
 Base.getproperty(::SenpiToolProxy, name::Symbol) = SenpiToolCallable(string(name))
 const tool = SenpiToolProxy()
 
+struct SenpiBridgeError <: Exception
+    message::String
+    code::Union{String, Nothing}
+end
+Base.showerror(io::IO, error::SenpiBridgeError) = Base.print(io, error.message)
+
+function senpi_workpool_call(args)
+    try
+        return tool.workpool(args)
+    catch error
+        if error isa SenpiBridgeError && error.code in ("unknown_tool", "inactive_tool")
+            throw(SenpiBridgeError("No active host workpool tool", "workpool_unavailable"))
+        end
+        rethrow()
+    end
+end
+
+struct SenpiWorkpool
+    pool_id::String
+end
+
+function Base.getproperty(pool::SenpiWorkpool, name::Symbol)
+    pool_id = getfield(pool, :pool_id)
+    name === :pool_id && return pool_id
+    name === :push && return items -> senpi_workpool_call(Dict("op" => "push", "pool_id" => pool_id, "items" => items))
+    name in (:close, :inspect, :cancel) && return () -> senpi_workpool_call(Dict("op" => string(name), "pool_id" => pool_id))
+    getfield(pool, name)
+end
+
+function workpool(agent::AbstractDict, name::AbstractString; mode=nothing)
+    args = Dict{String, Any}("op" => "create", "agent" => agent, "name" => name)
+    mode !== nothing && (args["mode"] = mode)
+    result = senpi_workpool_call(args)
+    details = get(result, "details", nothing)
+    if details isa AbstractDict
+        error = get(details, "error", nothing)
+        error isa AbstractDict && throw(SenpiBridgeError(error["message"], error["code"]))
+        pool_id = get(details, "pool_id", nothing)
+        if get(result, "hasError", false) !== true && pool_id isa AbstractString && occursin(r"^wp_[0-9a-f]{32}$", pool_id)
+            return SenpiWorkpool(pool_id)
+        end
+    end
+    throw(SenpiBridgeError("Host did not return a workpool identity", "workpool_unavailable"))
+end
+
 function completion(prompt::AbstractString; model="default", system=nothing, schema=nothing, kwargs...)
     options = Dict{String, Any}("model" => model)
     system !== nothing && (options["system"] = system)
@@ -225,6 +270,7 @@ function agent(prompt::AbstractString; agent="task", model=nothing, label=nothin
     handle || return parsed
     result = Dict{String, Any}("text" => text_value, "output" => text_value, "id" => get(record, "id", nothing), "agent" => get(record, "agent", agent))
     result["handle"] = get(record, "handle", result["id"] === nothing ? nothing : "agent://" * string(result["id"]))
+    result["run_epoch"] = get(record, "run_epoch", nothing)
     schema !== nothing && (result["data"] = parsed)
     result
 end

package/node_modules/@code-yeongyu/senpi-codemode/src/kernels/jl/runner.jl

@@ -244,7 +244,7 @@ function senpi_bridge_request(path::String, payload)
         parsed isa AbstractDict || error("Bridge returned invalid JSON")
         get(parsed, "ok", false) === true && return get(parsed, "value", nothing)
         failure = get(parsed, "error", parsed)
-        error(failure isa AbstractDict ? string(get(failure, "message", failure)) : string(failure))
+        throw(SenpiBridgeError(failure isa AbstractDict ? string(get(failure, "message", failure)) : string(failure), failure isa AbstractDict ? get(failure, "code", nothing) : nothing))
     finally
         close(socket)
     end

package/node_modules/@code-yeongyu/senpi-codemode/src/kernels/js/context-manager.ts

@@ -8,8 +8,12 @@ import {
 	type JavaScriptRunInput,
 	type LifecycleState,
 	type ResultMessage,
+	resolveKernelToolNameSource,
 	type ToolCallMessage,
 } from "./kernel-contract.ts";
+import { kernelToolError } from "./kernel-tools-errors.ts";
+import { KernelToolHostPump } from "./kernel-tools-host.ts";
+import type { KernelToolsDescribeResult, KernelToolsInvokeRequest } from "./kernel-tools-types.ts";
 import { type JavaScriptKernelOptions, LocalModuleLoader } from "./local-module-loader.ts";
 import { terminateProcessTrees } from "./process-tree-host.ts";
 import { JavaScriptRunQueue, type PendingJavaScriptRun, stoppedResult } from "./run-queue.ts";
@@ -36,6 +40,10 @@ export class JavaScriptKernel {
 	#recovery: Promise<void> | null = null;
 	#closePromise: Promise<void> | null = null;
 	readonly #runs = new JavaScriptRunQueue();
+	readonly #kernelTools = new KernelToolHostPump(
+		(message) => this.#slot.postMessage(message),
+		() => this.#lifecycle === "open" && this.#slot.present,
+	);
 	#timeout: NodeJS.Timeout | null = null;
 	#toolWaiters: Array<(message: ToolCallMessage) => void> = [];
 	#pendingToolCalls: ToolCallMessage[] = [];
@@ -56,6 +64,18 @@ export class JavaScriptKernel {
 		return this.#slot.mode;
 	}
 
+	get kernelToolEvents(): EventTarget {
+		return this.#kernelTools.events;
+	}
+
+	describeKernelTools(names: readonly string[]): Promise<KernelToolsDescribeResult> {
+		return this.#kernelTools.describe(names);
+	}
+
+	invokeKernelTool(request: KernelToolsInvokeRequest, signal?: AbortSignal): Promise<unknown> {
+		return this.#kernelTools.invoke(request, signal);
+	}
+
 	async run(input: JavaScriptRunInput): Promise<ResultMessage> {
 		assertJavaScriptKernelOpen(this.#lifecycle, "run");
 		const promise = this.#runs.enqueue(input);
@@ -102,6 +122,7 @@ export class JavaScriptKernel {
 		this.#slot.postMessage({ type: "close" });
 		this.#lifecycle = "closing";
 		this.#runs.settleAll("JS kernel closed");
+		this.#kernelTools.rejectAll(kernelToolError("kernel_tool_stale", "JS kernel closed"));
 		this.#clearToolCalls();
 		const recovery = this.#recovery;
 		const closePromise = (async () => {
@@ -146,6 +167,11 @@ export class JavaScriptKernel {
 		if (next.input.timeoutMs) {
 			this.#timeout = setTimeout(() => void this.#timeoutActive(next), next.input.timeoutMs);
 		}
+		this.#slot.postMessage({
+			type: "kernel-tools-names",
+			hostToolNames: resolveKernelToolNameSource(this.#options.hostToolNames),
+			foreignLanguageNames: resolveKernelToolNameSource(this.#options.foreignLanguageNames),
+		});
 		this.#slot.postMessage({
 			type: "run",
 			cellId: next.input.cellId,
@@ -220,6 +246,7 @@ export class JavaScriptKernel {
 	}
 
 	#handleMessage(message: KernelToHostMessage): void {
+		if (this.#kernelTools.consume(message) && message.type !== "tool-call") return;
 		if (message.type === "status" && message.event.op === INTERRUPT_ACK_OP) {
 			this.#runs.active?.interruptAck?.resolve();
 			return;
@@ -253,6 +280,7 @@ export class JavaScriptKernel {
 		const active = this.#runs.active;
 		if (!active && this.#slot.startingUp) return;
 		this.#clearTimeout();
+		this.#kernelTools.rejectAll(kernelToolError("kernel_tool_stale", error.message));
 		if (active) {
 			this.#runs.releaseActive(active);
 			this.#runs.settle(active, {
@@ -290,6 +318,7 @@ export class JavaScriptKernel {
 	 */
 	async #terminate(): Promise<WorkerRetirement> {
 		this.#clearTimeout();
+		this.#kernelTools.rejectAll(kernelToolError("kernel_tool_stale", "JavaScript worker reset"));
 		const retirement = await this.#slot.retire();
 		await this.#retireWorkerChildren();
 		return retirement;

package/node_modules/@code-yeongyu/senpi-codemode/src/kernels/js/kernel-contract.ts

@@ -6,6 +6,14 @@ export type ToolCallMessage = Extract<KernelToHostMessage, { type: "tool-call" }
 
 export type JavaScriptKernelMode = "worker" | "inline";
 
+/** Snapshot or live provider consulted when the worker registry checks collisions. */
+export type KernelToolNameSource = readonly string[] | (() => readonly string[]);
+
+export function resolveKernelToolNameSource(names?: KernelToolNameSource): string[] {
+	if (typeof names === "function") return [...names()];
+	return names === undefined ? [] : [...names];
+}
+
 export interface JavaScriptKernelOptions {
 	readonly sessionId: string;
 	readonly cwd: string;
@@ -14,6 +22,10 @@ export interface JavaScriptKernelOptions {
 	readonly workerEntryUrl?: URL;
 	/** Per-session PI_* values applied to the worker environment before the first cell runs. */
 	readonly sessionEnv?: SessionEnvironment;
+	/** Host tool names denied as JS kernel-tool identifiers (init protocol). */
+	readonly hostToolNames?: KernelToolNameSource;
+	/** Tool names registered in another kernel language, denied as JS kernel-tool identifiers. */
+	readonly foreignLanguageNames?: KernelToolNameSource;
 }
 
 export interface JavaScriptRunInput {

package/node_modules/@code-yeongyu/senpi-codemode/src/kernels/js/kernel-tools-context.d.ts

@@ -0,0 +1,13 @@
+export const kernelToolCallContext: {
+	run<T>(store: KernelToolCallStore, fn: () => T): T;
+	getStore(): KernelToolCallStore | undefined;
+};
+
+export type KernelToolCallStore = {
+	readonly pendingTools: Map<string, { resolve: (value: unknown) => void; reject: (error: Error) => void }>;
+	readonly callId: string;
+	readonly generation: number;
+	readonly signal: AbortSignal;
+};
+
+export function inKernelToolInvoke(): boolean;

package/node_modules/@code-yeongyu/senpi-codemode/src/kernels/js/kernel-tools-context.js

@@ -0,0 +1,7 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+export const kernelToolCallContext = new AsyncLocalStorage();
+
+export function inKernelToolInvoke() {
+	return kernelToolCallContext.getStore() != null;
+}

package/node_modules/@code-yeongyu/senpi-codemode/src/kernels/js/kernel-tools-define.d.ts

@@ -0,0 +1,10 @@
+export type KernelToolFunction = {
+	readonly name: string;
+};
+
+export function createToolNamespace(
+	define: (fn: KernelToolFunction, metadata?: unknown) => unknown,
+	callHost: (name: string, args: unknown) => Promise<unknown>,
+): ((fn: KernelToolFunction, metadata?: unknown) => unknown) & {
+	readonly [name: string]: (args?: unknown) => Promise<unknown>;
+};

package/node_modules/@code-yeongyu/senpi-codemode/src/kernels/js/kernel-tools-define.js

@@ -0,0 +1,12 @@
+export function createToolNamespace(define, callHost) {
+	const registrar = function tool(fn, metadata) {
+		return define(fn, metadata);
+	};
+	return new Proxy(registrar, {
+		get(target, prop) {
+			if (typeof prop !== "string") return undefined;
+			if (prop in Function.prototype || prop === "arguments" || prop === "caller") return target[prop];
+			return async (args) => await callHost(prop, args ?? {});
+		},
+	});
+}

package/node_modules/@code-yeongyu/senpi-codemode/src/kernels/js/kernel-tools-errors.js

@@ -0,0 +1,22 @@
+export const KERNEL_TOOL_ERROR_CODES = Object.freeze([
+	"tools_unavailable",
+	"invalid_tool_definition",
+	"reserved_tool_name",
+	"tool_name_collision",
+	"kernel_tool_stale",
+	"kernel_tool_missing",
+	"kernel_tool_failed",
+	"kernel_tool_recursion",
+]);
+
+export class KernelToolError extends Error {
+	constructor(code, message) {
+		super(message);
+		this.name = "KernelToolError";
+		this.code = code;
+	}
+}
+
+export function kernelToolError(code, message) {
+	return new KernelToolError(code, message);
+}

package/node_modules/@code-yeongyu/senpi-codemode/src/kernels/js/kernel-tools-errors.ts

@@ -0,0 +1,26 @@
+export const KERNEL_TOOL_ERROR_CODES = [
+	"tools_unavailable",
+	"invalid_tool_definition",
+	"reserved_tool_name",
+	"tool_name_collision",
+	"kernel_tool_stale",
+	"kernel_tool_missing",
+	"kernel_tool_failed",
+	"kernel_tool_recursion",
+] as const;
+
+export type KernelToolErrorCode = (typeof KERNEL_TOOL_ERROR_CODES)[number];
+
+export class KernelToolError extends Error {
+	readonly name = "KernelToolError";
+	readonly code: KernelToolErrorCode;
+
+	constructor(code: KernelToolErrorCode, message: string) {
+		super(message);
+		this.code = code;
+	}
+}
+
+export function kernelToolError(code: KernelToolErrorCode, message: string): KernelToolError {
+	return new KernelToolError(code, message);
+}