@code-yeongyu/senpi-codemode 2026.10.6 → 2026.10.8

package/CHANGELOG.md

@@ -12,6 +12,43 @@
 
 ### Removed
 
+## [2026.10.8] - 2026-10-04
+
+### Breaking Changes
+
+### Added
+
+- Internal groundwork for installing Python packages from a cell: per-session environment revisions that are published only after a successful install (a failed or interrupted install leaves the previous revision active), a per-root install lock, and a pip installer that always targets the session's own directory. Not exposed to cells yet ([#2452](https://github.com/code-yeongyu/senpi/issues/2452)).
+- Python kernel tools: `@tool` registers a function that in-process children can call, with its schema inferred from type hints; callbacks are served while the kernel is idle or its cell waits on a host call, never during a running computation, and a reset or redefinition makes old descriptors stale. `tool.defined()` / `tool.undefine()` in Python, and `tool_schema("eval:kernel-tools")` ([#2452](https://github.com/code-yeongyu/senpi/issues/2452)).
+- Internal groundwork for isolated sandbox cells: a vendored copy of the pi codemode runtime (QuickJS in a worker) with two opt-in host options, output streaming bounded by a credit window and a store policy that keeps no state. Nothing uses it yet ([#2452](https://github.com/code-yeongyu/senpi/issues/2452)).
+
+### Changed
+
+### Fixed
+
+- A cold Python kernel start on a busy machine no longer fails as a hang: startup keeps waiting while the interpreter is still using CPU or writing output, and fails only when it has gone completely still (naming the stage), or after 120 s without becoming ready ([#2718](https://github.com/code-yeongyu/senpi/issues/2718)).
+
+### Removed
+
+## [2026.10.7] - 2026-10-04
+
+### Breaking Changes
+
+### Added
+
+- JavaScript kernel tools: `tool.defined()` lists the defined kernel tools and `tool.undefine(name)` removes one; `tool(fn, { name })` registers a tool under an explicit name while keeping the function's argument order ([#2452](https://github.com/code-yeongyu/senpi/issues/2452)).
+- In-cell `wait(handles, {timeout, mode})` barrier and `handle(node | ref | {pool_id})` rich views in all four kernels: `wait` returns values in input order (`all`), the first success (`any`) or every outcome (`settled`), times out with `eval_wait_timeout` without cancelling work, and pauses the run budget while parked; `handle(node).control` offers `status()`, `output()`, `send()`, `cancel()` and `wait()` fenced by owner, id and `run_epoch` through the host's `EvalHandleHost` capability (agent and workpool handles fail with `eval_wait_unavailable` on a host without it); `completion(prompt, {handle: true})` returns an opt-in completion handle bounded by its cell's hard deadline; `tool_schema("eval:helpers")` and `tool_schema("eval:wait")` document the surface and the removed-tool hint for `wait` points at them. The legacy `agent(..., {handle: true})` record, the eval description and the eval input schema are unchanged; the Python runner's dispatcher was renamed `_handle_message` so `handle()` is the helper ([#2687](https://github.com/code-yeongyu/senpi/pull/2687)).
+
+### Changed
+
+### Fixed
+
+- The Ruby kernel's memory notice names the largest globals again on Ruby 2.6 (the sizer used a Ruby 2.7 method) ([#2696](https://github.com/code-yeongyu/senpi/issues/2696)).
+- Eval no longer fails with "codemode session manager is disposed" for the rest of a session after a session switch or fork that another extension cancelled: codemode only tears its kernels down when the session actually ends ([#1706](https://github.com/code-yeongyu/senpi/issues/1706)).
+- A session whose codemode runtime failed to start is recovered by the next eval call (once, with one stderr line naming the failed start); if re-creation also fails, the call says "codemode runtime could not be re-created: <reason>" and how to bring eval back ([#1706](https://github.com/code-yeongyu/senpi/issues/1706)).
+
+### Removed
+
 ## [2026.10.6] - 2026-10-04
 
 ### Breaking Changes

package/README.md

@@ -200,8 +200,13 @@ options object and asynchronous helpers are `await`-able.
 | `env(key?, value?)` | Reads all kernel environment values, one value, or sets one value. Includes the session's `PI_*` values (see [Session environment](#session-environment)). |
 | `tool.<name>(args)` | Invokes an active Senpi tool through the normal `pi.executeTool` pipeline and returns `{ text, images?, details?, hasError? }` in every kernel; image blocks arrive as `images[i] = { mimeType, dataBase64 }`. |
 | `tool_schema(name?)` | Returns a tool's parameter schema without calling it; omit `name` to list tool names. |
+| `tool(fn, metadata?)` (js) | Registers a named function as a kernel tool for in-process children. `metadata.name` registers it under that name instead of the function's; arguments are still passed in the function's parameter order. |
+| `tool.defined()` / `tool.undefine(name)` (js) | List the kernel tools this kernel defines (sorted), and remove one (`true` if it existed). A descriptor taken before `undefine` can no longer be invoked. Both names are reserved: a kernel tool can't be registered as `defined` or `undefine` (`reserved_tool_name`), and a host tool with either name is shadowed in the `tool` namespace, so it can't be called from a JavaScript cell. |
+| `@tool` / `@tool(name=, description=, schema=)` (py) | Registers a Python function as a kernel tool for in-process children; the schema is inferred from its type hints (`tool_schema("eval:kernel-tools")` lists the rules). Callbacks run while the kernel is idle or its cell is parked in a host call, never in the middle of a running computation. `tool.defined()` and `tool.undefine(name)` work as in JavaScript. Ruby and Julia kernels answer `tools_unavailable`. |
 | `completion(prompt, model?, system?, schema?)` | Requests a one-shot host completion; `schema` asks the host to parse structured output. |
 | `agent(prompt, ...)` | Delegates to the configured active `taskTools.task` tool. Supports background handles and structured JSON results. |
+| `wait(handles, timeout?, mode?)` | Blocks the cell until the given handles settle (agent handle records, `handle()` views, completion handles, closed workpools, or saved `{kind, id, run_epoch}` references). `mode` is `all` (values in input order; the first failed, cancelled, or lost handle raises), `any` (`{index, ref, value}` of the first success), or `settled` (one outcome per input slot). `timeout` is wall-clock seconds from entry; on expiry `eval_wait_timeout` is raised and nothing is cancelled. Rides the bridge-call path, so the run budget pauses while parked. Agent and workpool handles need the host's `EvalHandleHost` capability (`eval_wait_unavailable` without it); completion handles always work. Julia extends `Base.wait` for handle views (`wait(handle(node))`). Details: `tool_schema("eval:wait")`. |
+| `handle(node \| ref \| {pool_id})` | Returns a rich view: the legacy record's fields plus a non-enumerable `control` (Python: attribute on a `dict` subclass; Ruby: singleton method) with `status()`, `output(format?, offset?, limit?)`, `send(message)` (agent handles only), `cancel()` (idempotent for that run epoch; never touches a successor run), and `wait(timeout?)`. Every control call is fenced by owner, id, and `run_epoch` inside the task owner (`eval_handle_stale`, `eval_handle_forbidden`). `completion(prompt, handle: true)` returns such a view for a host completion. The `agent(..., handle: true)` record itself is unchanged. Details: `tool_schema("eval:helpers")`. |
 | `workpool(agent, name, mode?)` | Creates a thin adapter over the normal host `workpool` tool; exposes `pool_id`, `push(items)`, `close()`, `inspect()`, and `cancel()`. JS awaits creation and operations. |
 | `output(ids, format?, offset?, limit?)` | Delegates transcript retrieval to the configured active `taskTools.output` tool. |
 | `parallel(thunks)` | Runs thunks through the configured bounded pool while preserving input order. |
@@ -457,8 +462,21 @@ Homebrew (put `/opt/homebrew/opt/ruby/bin` first on `PATH`; macOS's system Ruby
 before `--write-baseline`.
 
 The report is gitignored `gate-report.json` by default (`--report <path>` overrides it).
-`test/gate/allowlist.json` contains reviewed additive changes keyed by plan node;
-it cannot authorize removal or modification of a legacy entry. The test-only
+`test/gate/allowlist.json` contains reviewed additive changes keyed by plan node.
+A pull request that changes the committed `baseline.json` itself (an intended
+schema or prompt change, a renamed contract, a deleted module) must list every
+cell it edits or removes under that node's `changes`, each as
+`{ "key": "<section>/<cell>", "reason": "..." }`. In a pull request the gate reads
+the baseline at the merge base and fails any baseline edit or removal that is
+not listed, any edited or added cell that differs from what the head measures,
+and any listed removal the head still measures. A cell written into the baseline that
+was absent at the merge base must be listed under some node's `additions` (an entry an earlier
+pull request added counts, so a re-record can write in cells approved before); only `changes`
+entries must be new in this pull request. Reviewers read each `changes`
+entry: it is the only record of why a protected surface moved. If the merge
+base cannot be resolved in a pull request, the gate fails closed; the gate job
+checks out full history for this. A local run outside a pull request reviews
+baseline changes only with `--base-ref <ref>`. The test-only
 `SENPI_CODEMODE_GATE_MUTATE=drop-phase` report mutation proves that helper removal
 is rejected. `SENPI_CODEMODE_GATE_MUTATE=leak-kernel` leaves the real kernel
 alive at the teardown witness, then closes it in `finally`; nonzero process,

package/package.json

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

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

@@ -92,12 +92,20 @@ export const kernelToolKernelToHostSchemas = [
 		requestId: Type.String({ minLength: 1 }),
 		ok: Type.Literal(true),
 		value: Type.Unknown(),
+		/** Python: text the tool printed during this call (never the parent cell's output). */
+		output: Type.Optional(Type.String()),
 	}),
 	Type.Object({
 		type: Type.Literal("kernel-tool-invoke-reply"),
 		requestId: Type.String({ minLength: 1 }),
 		ok: Type.Literal(false),
 		error: kernelToolErrorSchema,
+		output: Type.Optional(Type.String()),
+	}),
+	/** Python: the kernel's tool names after a define or undefine, for cross-language collision checks. */
+	Type.Object({
+		type: Type.Literal("kernel-tools-defined"),
+		names: Type.Array(Type.String({ minLength: 1 })),
 	}),
 ] as const;
 

package/src/bridge/reserved.ts

@@ -5,6 +5,16 @@ export const RESERVED_AGENT_TOOL = "__agent__" as const;
 export const RESERVED_OUTPUT_TOOL = "__output__" as const;
 /** ADAPTATION: senpi resolves tool parameter schemas through a reserved kernel-side tool name. */
 export const RESERVED_SCHEMA_TOOL = "__schema__" as const;
+/** In-cell `wait(handles)` barrier over the host's EvalHandleHost subscription capability. */
+export const RESERVED_WAIT_TOOL = "__wait__" as const;
+/** `handle(node).control.status()`: one epoch-fenced snapshot through the host's `watch`. */
+export const RESERVED_HANDLE_STATUS_TOOL = "__handle_status__" as const;
+/** `handle(node).control.output(opts)`: the transcript of exactly `ref.run_epoch`. */
+export const RESERVED_HANDLE_OUTPUT_TOOL = "__handle_output__" as const;
+/** `handle(node).control.send(message)`: agent handles only, fenced inside the task owner. */
+export const RESERVED_HANDLE_SEND_TOOL = "__handle_send__" as const;
+/** `handle(node).control.cancel()`: idempotent for its epoch; a successor run is never touched. */
+export const RESERVED_HANDLE_CANCEL_TOOL = "__handle_cancel__" as const;
 /** Canonical oh-my-pi eval-timeout pause operation. */
 export const TIMEOUT_PAUSE_OP = "timeout-pause" as const;
 /** Canonical oh-my-pi eval-timeout resume operation. */

package/src/bridges/eval-virtual-schemas.ts

@@ -0,0 +1,100 @@
+import type { EvalSchemaResult } from "./schema-bridge.ts";
+
+/**
+ * Virtual `tool_schema("eval:*")` entries: documentation a cell can read on demand. They are not tools,
+ * never execute anything, and never appear in the ordinary catalog listing, so the eval prompt and the
+ * host tool list stay byte-identical.
+ */
+const handleRefSchema = {
+	type: "object",
+	description:
+		"A saved handle reference. agent(..., {handle: true}) records, handle() views, completion handles and workpools ({pool_id}) are accepted directly.",
+	properties: {
+		kind: { enum: ["agent", "completion", "workpool"] },
+		id: { type: "string" },
+		run_epoch: {
+			type: "integer",
+			minimum: 0,
+			description:
+				"The run this reference is bound to; a resumed task gets a new epoch and the old reference fails with eval_handle_stale.",
+		},
+	},
+	required: ["kind", "id", "run_epoch"],
+} as const;
+
+const waitEntry: EvalSchemaResult = {
+	name: "eval:wait",
+	description: [
+		"wait(handles, {timeout?, mode?}) blocks the cell until the given handles settle (js: await wait(...); py/rb: wait(...); jl: wait(handle(node)) or wait([handle(a), handle(b)])).",
+		'mode "all" (default) returns the successful values in input order and raises the first failed, cancelled or lost handle\'s error; "any" returns {index, ref, value} of the first success or eval_wait_all_rejected; "settled" returns one {status, ref, value|error} outcome per input slot.',
+		"Duplicates keep their slots with one subscription. Empty handles: all/settled -> [], any -> eval_wait_empty.",
+		"timeout is wall-clock seconds from entry (finite, >= 0; 0 = one atomic check; omitted = no wait-specific deadline). On timeout the subscription closes and `eval_wait_timeout: wait() timed out after Ns; k/n handles settled; work was not cancelled` is raised. wait() never cancels work.",
+		"wait() rides the bridge-call path: the cell's run budget pauses while parked, the hard limit never pauses, and a long barrier detaches like any bridge-parked cell. Cancelling the cell closes its subscriptions at once. Task and workpool notifications are neither consumed nor suppressed.",
+		"A workpool must be closed first (eval_pool_open) and succeeds only when every key succeeds (eval_workpool_failed carries the keyed aggregate).",
+		"Agent and workpool handles need the host capability; without it wait() fails with eval_wait_unavailable and never polls task_output. Completion handles always work.",
+	].join("\n"),
+	parameters: {
+		type: "object",
+		properties: {
+			handles: { type: "array", items: handleRefSchema },
+			timeout: { type: "number", minimum: 0, description: "Wall-clock seconds from entry." },
+			mode: { enum: ["all", "any", "settled"], default: "all" },
+		},
+		required: ["handles"],
+	},
+};
+
+const helpersEntry: EvalSchemaResult = {
+	name: "eval:helpers",
+	description: [
+		"Advanced cell helpers (all four languages; js helpers are awaited).",
+		"handle(node | ref | {pool_id}) returns a rich view: the legacy fields plus a non-enumerable `control` (py: attribute, rb: singleton method) with status(), output({format, offset, limit}), send(message) (agent handles only; others eval_handle_operation_unsupported), cancel() (idempotent for that run epoch; never cancels a successor run) and wait({timeout}).",
+		"control.status() goes through the host subscription; control.send/cancel/output are fenced by owner, id and run_epoch inside the task owner (stale -> eval_handle_stale, foreign -> eval_handle_forbidden); control.output() returns only that epoch's transcript. The plain output() helper and task tools are unchanged.",
+		"The legacy agent(..., {handle: true}) record is unchanged: .output stays a string and no enumerable key is added. A saved {kind, id, run_epoch} (or the record itself) can be rebound with handle(ref) in a later cell or after a kernel reset while the owner and run epoch are valid.",
+		"completion(prompt, {handle: true}) (py: handle=True) returns a control handle after preflight validation; provider failures surface in its outcome; its deadline derives from the creating cell's hard deadline. Completion handles are codemode-owned and need no host capability; once the session generation is dropped they fail with eval_handle_stale.",
+		"See tool_schema('eval:wait') for the barrier semantics.",
+	].join("\n"),
+	parameters: {
+		type: "object",
+		properties: {
+			wait: { description: "wait(handles, {timeout?, mode?}) -> values | {index, ref, value} | outcomes[]" },
+			handle: { description: "handle(node | ref | {pool_id}) -> view with .control" },
+			"control.status": { description: "() -> {ref, phase, host_status, revision}" },
+			"control.output": { description: "({format?, offset?, limit?}) -> {ref, text, offset, total, truncated}" },
+			"control.send": { description: "(message) -> snapshot; agent handles only" },
+			"control.cancel": { description: "() -> {ref, cancelled, phase}" },
+			"control.wait": { description: "({timeout?}) -> value" },
+			completion: { description: "completion(prompt, {handle: true}) -> control handle" },
+		},
+	},
+};
+
+const kernelToolsEntry: EvalSchemaResult = {
+	name: "eval:kernel-tools",
+	description: [
+		"Kernel tools: functions a cell defines that in-process children can call (js and py; rb/jl answer tools_unavailable).",
+		"js: tool(fn, {name?, description?, schema?}) registers a named function; arguments are passed in its parameter order; without schema only the parameter names are inferred and every one is required.",
+		'py: @tool or @tool(name=..., description=..., schema=...) registers the function and returns it unchanged. The schema is inferred from type hints (str, int, float, bool, None, list[T], dict[str, T], Literal, unions and Optional as nullable, Annotated[T, "description"], keyword-only parameters); a JSON default makes a parameter optional; string annotations (from __future__ import annotations) resolve through the function\'s globals. Positional-only, *args, **kwargs and unresolvable or unsupported annotations are refused with invalid_tool_definition unless schema= is given. The function is never called to infer anything.',
+		"tool.defined() lists this kernel's kernel tools (sorted); tool.undefine(name) removes one (true if it existed). The names defined and undefine are reserved.",
+		"Grants: a child is given descriptors (name, kernel_generation, definition_revision) before it starts. A reset, restart or redefinition makes an old descriptor fail with kernel_tool_stale; the new definition never satisfies it. A name defined in both js and py fails describe with tool_name_collision.",
+		"py callbacks run while the kernel is idle or its cell is parked in a host call (a tool call, wait(), an install); a cell busy in pure computation is never interrupted, the callback waits. A callback's printed text goes to its own reply, never the parent cell's output. Cancelling a call ends it at its next host call (kernel_tool_cancelled); a computation already running finishes and its result is dropped. An awaited object from the parent cell's event loop fails with kernel_tool_loop_mismatch.",
+	].join("\n"),
+	parameters: {
+		type: "object",
+		properties: {
+			tool: { description: "js: tool(fn, metadata?); py: @tool / @tool(name=, description=, schema=)" },
+			"tool.defined": { description: "() -> names[]" },
+			"tool.undefine": { description: "(name) -> boolean" },
+		},
+	},
+};
+
+const VIRTUAL_ENTRIES: ReadonlyMap<string, EvalSchemaResult> = new Map([
+	[waitEntry.name, waitEntry],
+	[helpersEntry.name, helpersEntry],
+	[kernelToolsEntry.name, kernelToolsEntry],
+]);
+
+export function virtualEvalSchema(name: string): EvalSchemaResult | undefined {
+	return VIRTUAL_ENTRIES.get(name);
+}

package/src/bridges/handle-bridge.ts

@@ -0,0 +1,72 @@
+import { EvalHandleError, type EvalHandleHost } from "@code-yeongyu/senpi";
+import {
+	RESERVED_HANDLE_CANCEL_TOOL,
+	RESERVED_HANDLE_OUTPUT_TOOL,
+	RESERVED_HANDLE_SEND_TOOL,
+	RESERVED_HANDLE_STATUS_TOOL,
+	RESERVED_WAIT_TOOL,
+} from "../bridge/reserved.ts";
+import { parseOutputArgs, parseRefArgs, parseSendArgs, parseWaitArgs } from "../handles/handle-args.ts";
+import type { HandleBackend, HandleRegistry } from "../handles/handle-registry.ts";
+import { waitForHandles } from "../handles/wait.ts";
+
+export const HANDLE_TOOL_NAMES = [
+	RESERVED_WAIT_TOOL,
+	RESERVED_HANDLE_STATUS_TOOL,
+	RESERVED_HANDLE_OUTPUT_TOOL,
+	RESERVED_HANDLE_SEND_TOOL,
+	RESERVED_HANDLE_CANCEL_TOOL,
+] as const;
+
+export type HandleToolName = (typeof HANDLE_TOOL_NAMES)[number];
+
+export interface HandleBridgeContext {
+	/** The session generation's registry; absent only for the pre-session baseline tool. */
+	readonly registry: HandleRegistry | undefined;
+	/** `ctx.evalHandleHost` at dispatch time; absent on a runtime without a provider. */
+	readonly host: EvalHandleHost | undefined;
+	/** The calling cell's signal: cancelling the cell closes its subscriptions immediately. */
+	readonly signal: AbortSignal | undefined;
+}
+
+export function isHandleToolName(toolName: string): toolName is HandleToolName {
+	return HANDLE_TOOL_NAMES.some((name) => name === toolName);
+}
+
+/** Dispatches the five reserved handle tools; every path is fenced by the registry before any host call. */
+export async function runHandleTool(toolName: HandleToolName, args: unknown, context: HandleBridgeContext) {
+	const registry = context.registry;
+	if (registry === undefined) {
+		throw new EvalHandleError(
+			"eval_wait_unavailable",
+			"wait()/handle() are not supported by this runtime: this session has no handle registry yet",
+		);
+	}
+	const backend: HandleBackend = { host: context.host, signal: context.signal };
+	switch (toolName) {
+		case RESERVED_WAIT_TOOL:
+			return await waitForHandles(parseWaitArgs(args), {
+				watch: (refs) => registry.watch(refs, backend),
+				result: (ref) => registry.result(ref, backend),
+				...(context.signal === undefined ? {} : { signal: context.signal }),
+			});
+		case RESERVED_HANDLE_STATUS_TOOL:
+			return await registry.status(parseRefArgs(args, "control.status()"), backend);
+		case RESERVED_HANDLE_OUTPUT_TOOL: {
+			const { ref, request } = parseOutputArgs(args);
+			return await registry.output(ref, request, backend);
+		}
+		case RESERVED_HANDLE_SEND_TOOL: {
+			const { ref, message } = parseSendArgs(args);
+			return await registry.send(ref, message, backend);
+		}
+		case RESERVED_HANDLE_CANCEL_TOOL:
+			return await registry.cancel(parseRefArgs(args, "control.cancel()"), backend);
+		default:
+			return assertNever(toolName);
+	}
+}
+
+function assertNever(value: never): never {
+	throw new TypeError(`Unsupported handle tool: ${String(value)}`);
+}

package/src/bridges/reserved-dispatch.ts

@@ -1,7 +1,9 @@
-import type { AgentToolResult } from "@code-yeongyu/senpi";
+import type { AgentToolResult, EvalHandleHost } from "@code-yeongyu/senpi";
 import { RESERVED_AGENT_TOOL, RESERVED_OUTPUT_TOOL, RESERVED_SCHEMA_TOOL } from "../bridge/reserved.ts";
+import type { HandleRegistry } from "../handles/handle-registry.ts";
 import type { EvalStatusEvent, ExecuteTool } from "../tool/types.ts";
 import { type AgentExecuteTool, runEvalAgent } from "./agent-bridge.ts";
+import { isHandleToolName, runHandleTool } from "./handle-bridge.ts";
 import { type MarshalledToolResult, type OutputExecuteTool, runEvalOutput } from "./output-bridge.ts";
 import { type EvalSchemaToolInfo, runEvalSchema } from "./schema-bridge.ts";
 
@@ -15,6 +17,10 @@ export interface ReservedDispatchContext {
 	readonly signal: AbortSignal | undefined;
 	readonly emitStatus: (event: EvalStatusEvent) => void;
 	readonly marshalToolResult: (result: AgentToolResult<unknown>) => MarshalledToolResult;
+	/** The session generation's handle registry; `wait()`/`handle()` fail with `eval_wait_unavailable` without one. */
+	readonly handles?: HandleRegistry;
+	/** `ctx.evalHandleHost` at dispatch time; agent/workpool refs need it, completion refs do not. */
+	readonly evalHandleHost?: EvalHandleHost;
 }
 
 class SchemaUnavailableError extends Error {
@@ -26,10 +32,22 @@ class SchemaUnavailableError extends Error {
 }
 
 export function isReservedToolName(toolName: string): boolean {
-	return toolName === RESERVED_AGENT_TOOL || toolName === RESERVED_OUTPUT_TOOL || toolName === RESERVED_SCHEMA_TOOL;
+	return (
+		toolName === RESERVED_AGENT_TOOL ||
+		toolName === RESERVED_OUTPUT_TOOL ||
+		toolName === RESERVED_SCHEMA_TOOL ||
+		isHandleToolName(toolName)
+	);
 }
 
 export async function runReservedTool(toolName: string, context: ReservedDispatchContext): Promise<unknown> {
+	if (isHandleToolName(toolName)) {
+		return await runHandleTool(toolName, context.args, {
+			registry: context.handles,
+			host: context.evalHandleHost,
+			signal: context.signal,
+		});
+	}
 	if (toolName === RESERVED_AGENT_TOOL) {
 		return await runEvalAgent(context.args, {
 			callId: context.callId,

package/src/bridges/schema-bridge.ts

@@ -1,6 +1,7 @@
 import type { KernelPreludeContribution } from "@code-yeongyu/senpi";
 import { type Static, Type } from "typebox";
 import { Check, Errors } from "typebox/value";
+import { virtualEvalSchema } from "./eval-virtual-schemas.ts";
 
 const schemaArgsSchema = Type.Object(
 	{ name: Type.Optional(Type.String({ minLength: 1 })) },
@@ -46,6 +47,9 @@ export function runEvalSchema(args: unknown, options: RunEvalSchemaOptions): Eva
 	const tools = options.listTools();
 	if (parsed.name === undefined) return { tools: tools.map((tool) => tool.name) };
 
+	// Documentation-only entries; they are not tools and the listing above stays the ordinary catalog.
+	const virtual = virtualEvalSchema(parsed.name);
+	if (virtual !== undefined) return virtual;
 	const match = tools.find((tool) => tool.name === parsed.name);
 	if (match) return { name: match.name, description: match.description, parameters: match.parameters };
 	throw new SchemaUnknownToolError(parsed.name, nearestNames(parsed.name, tools));

package/src/completion/handle.ts

@@ -0,0 +1,69 @@
+import type { ExtensionContext, HandleRef } from "@code-yeongyu/senpi";
+import type { HandleRegistry } from "../handles/handle-registry.ts";
+import type { CompletionRequest, CompletionResult } from "./handler.ts";
+
+/** What `completion(prompt, {handle: true})` returns: a saved reference every prelude turns into a control view. */
+export interface CompletionHandleRecord {
+	readonly kind: "completion";
+	readonly id: string;
+	readonly run_epoch: number;
+	readonly handle: string;
+}
+
+export interface StartCompletionHandleOptions {
+	readonly registry: HandleRegistry;
+	readonly request: CompletionRequest;
+	readonly complete: (request: CompletionRequest, ctx: ExtensionContext) => Promise<CompletionResult>;
+	readonly ctx: ExtensionContext;
+	/** The creating cell's hard deadline (absolute ms); the completion is aborted at it. */
+	readonly deadlineMs: number;
+}
+
+const COMPLETION_TIERS: ReadonlySet<string> = new Set(["smol", "default", "slow"]);
+
+class CompletionHandleArgumentsError extends Error {
+	readonly name = "CompletionHandleArgumentsError";
+	readonly code = "eval_handle_invalid_arguments";
+
+	constructor(detail: string) {
+		super(`eval_handle_invalid_arguments: completion(prompt, {handle: true}) ${detail}`);
+	}
+}
+
+/** True when the completion call opted into a handle (`{handle: true}` in its options). */
+export function wantsCompletionHandle(opts: unknown): boolean {
+	return typeof opts === "object" && opts !== null && "handle" in opts && opts.handle === true;
+}
+
+/**
+ * Preflight-validates the request, then starts the completion in the session registry and returns its
+ * reference at once. Provider failures surface in the handle's outcome, never here.
+ */
+export function startCompletionHandle(options: StartCompletionHandleOptions): CompletionHandleRecord {
+	const request = withoutHandleOption(options.request);
+	if (request.prompt.trim().length === 0) throw new CompletionHandleArgumentsError("needs a non-empty prompt");
+	const tier = request.model ?? tierFromOpts(request.opts);
+	if (tier !== undefined && !COMPLETION_TIERS.has(tier)) {
+		throw new CompletionHandleArgumentsError(`got model tier "${tier}"; expected "smol", "default", or "slow"`);
+	}
+	const ref: HandleRef = options.registry.startCompletion({
+		deadlineMs: options.deadlineMs,
+		run: async (signal) => replyValue(await options.complete(request, { ...options.ctx, signal })),
+	});
+	return { kind: "completion", id: ref.id, run_epoch: ref.run_epoch, handle: `completion://${ref.id}` };
+}
+
+export function replyValue(result: CompletionResult): unknown {
+	return "value" in result ? result.value : result.text;
+}
+
+function tierFromOpts(opts: unknown): string | undefined {
+	if (typeof opts !== "object" || opts === null || !("model" in opts)) return undefined;
+	return typeof opts.model === "string" ? opts.model : undefined;
+}
+
+function withoutHandleOption(request: CompletionRequest): CompletionRequest {
+	if (typeof request.opts !== "object" || request.opts === null || !("handle" in request.opts)) return request;
+	const { handle: _handle, ...opts } = request.opts;
+	return { ...request, opts };
+}

package/src/completion/tool-bridge.ts

@@ -1,6 +1,8 @@
 import type { ExtensionContext } from "@code-yeongyu/senpi";
 import type { KernelToHostMessage } from "../bridge/protocol.ts";
+import type { HandleRegistry } from "../handles/handle-registry.ts";
 import type { EvalKernel } from "../tool/types.ts";
+import { replyValue, startCompletionHandle, wantsCompletionHandle } from "./handle.ts";
 import type { CompletionRequest, CompletionResult } from "./handler.ts";
 
 export interface CompletionToolCallOptions {
@@ -9,20 +11,28 @@ export interface CompletionToolCallOptions {
 	readonly complete: (request: CompletionRequest, ctx: ExtensionContext) => Promise<CompletionResult>;
 	readonly ctx: ExtensionContext;
 	readonly isActive: () => boolean;
+	/** Needed only for `completion(prompt, {handle: true})`; without it that option is refused. */
+	readonly handles?: HandleRegistry;
+	/** The creating cell's hard deadline (absolute ms) bounding a completion handle. */
+	readonly hardDeadlineMs?: number;
 }
 
 export type CompletionToolCallSummary = { readonly ok: true } | { readonly ok: false; readonly error: string };
 
 export async function handleCompletionToolCall(options: CompletionToolCallOptions): Promise<CompletionToolCallSummary> {
 	try {
-		const result = await options.complete(toCompletionRequest(options.message.args), options.ctx);
+		const request = toCompletionRequest(options.message.args);
+		const value = wantsCompletionHandle(request.opts)
+			? startCompletionHandle({
+					registry: requireRegistry(options.handles),
+					request,
+					complete: options.complete,
+					ctx: options.ctx,
+					deadlineMs: options.hardDeadlineMs ?? Number.POSITIVE_INFINITY,
+				})
+			: replyValue(await options.complete(request, options.ctx));
 		if (!options.isActive()) return { ok: false, error: "completion() result ignored after eval finalization" };
-		options.kernel.deliverToolReply({
-			type: "tool-reply",
-			callId: options.message.callId,
-			ok: true,
-			value: completionReplyValue(result),
-		});
+		options.kernel.deliverToolReply({ type: "tool-reply", callId: options.message.callId, ok: true, value });
 		return { ok: true };
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
@@ -31,12 +41,25 @@ export async function handleCompletionToolCall(options: CompletionToolCallOption
 			type: "tool-reply",
 			callId: options.message.callId,
 			ok: false,
-			error: { message },
+			error: {
+				message,
+				...(error instanceof Error && "code" in error && typeof error.code === "string"
+					? { code: error.code }
+					: {}),
+			},
 		});
 		return { ok: false, error: message };
 	}
 }
 
+function requireRegistry(handles: HandleRegistry | undefined): HandleRegistry {
+	if (handles !== undefined) return handles;
+	throw Object.assign(
+		new Error("eval_wait_unavailable: completion handles are not available before the session starts"),
+		{ code: "eval_wait_unavailable" },
+	);
+}
+
 function toCompletionRequest(value: unknown): CompletionRequest {
 	if (typeof value === "object" && value !== null && "prompt" in value && typeof value.prompt === "string") {
 		return {
@@ -49,7 +72,3 @@ function toCompletionRequest(value: unknown): CompletionRequest {
 	}
 	throw new Error("completion() received invalid arguments");
 }
-
-function completionReplyValue(result: CompletionResult): unknown {
-	return "value" in result ? result.value : result.text;
-}