@code-yeongyu/senpi-codemode 2026.7.26 → 2026.7.28

package/CHANGELOG.md

@@ -12,6 +12,22 @@
 
 ### Removed
 
+## [2026.7.28] - 2026-07-28
+
+### Breaking Changes
+
+### Added
+
+- Add `tool_schema()` and return parameter schemas from failed eval tool calls so cells can inspect and self-correct tool invocations ([#407](https://github.com/code-yeongyu/senpi/pull/407)).
+
+### Changed
+
+- Allow eval cells and extensions to activate named searchable tools lazily on the calling surface without globally widening the active tool set ([#408](https://github.com/code-yeongyu/senpi/pull/408)).
+
+### Fixed
+
+### Removed
+
 ## [2026.7.26] - 2026-07-26
 
 ### Breaking Changes

package/README.md

@@ -101,6 +101,7 @@ options object and asynchronous helpers are `await`-able.
 | `write(path, content)` | Creates parent directories and writes text. `local://` paths persist in the session artifact root. |
 | `env(key?, value?)` | Reads all kernel environment values, one value, or sets one value. |
 | `tool.<name>(args)` | Invokes an active Senpi tool through the normal `pi.executeTool` pipeline. |
+| `tool_schema(name?)` | Returns a tool's parameter schema without calling it; omit `name` to list tool names. |
 | `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. |
 | `output(ids, format?, offset?, limit?)` | Delegates transcript retrieval to the configured active `taskTools.output` tool. |
@@ -108,6 +109,11 @@ options object and asynchronous helpers are `await`-able.
 | `pipeline(items, ...stages)` | Applies stages left to right with a barrier between stages. |
 | `log(message)` / `phase(title)` | Emits progress text and starts a status phase. |
 
+When a `tool.<name>()` call fails argument validation, the error delivered back
+into the cell carries the tool's expected parameters, so the cell can correct the
+arguments and retry instead of falling back to one-at-a-time tool calls.
+`tool_schema()` exposes the same catalog up front.
+
 `agent()` is available only when the configured task tool is active in the
 session. `output()` similarly requires the configured task-output tool and
 returns immediately: a running task reports its current status, while completed

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/senpi-codemode",
-	"version": "2026.7.26",
+	"version": "2026.7.28",
 	"description": "Source-only senpi extension package for codemode evaluation tools",
 	"type": "module",
 	"main": "./src/index.ts",
@@ -30,14 +30,14 @@
 	},
 	"dependencies": {
 		"@babel/parser": "7.29.7",
-		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@^2026.7.26",
+		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@^2026.7.28",
 		"typebox": "1.1.38"
 	},
 	"peerDependencies": {
 		"@code-yeongyu/senpi": "*"
 	},
 	"devDependencies": {
-		"@code-yeongyu/senpi": "2026.7.26"
+		"@code-yeongyu/senpi": "2026.7.28"
 	},
 	"keywords": [
 		"senpi",

package/src/bridge/reserved.ts

@@ -3,6 +3,8 @@
 export const RESERVED_AGENT_TOOL = "__agent__" as const;
 /** ADAPTATION: senpi delegates output through a reserved kernel-side tool name. */
 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;
 /** 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/reserved-dispatch.ts

@@ -0,0 +1,56 @@
+import type { AgentToolResult } from "@code-yeongyu/senpi";
+import { RESERVED_AGENT_TOOL, RESERVED_OUTPUT_TOOL, RESERVED_SCHEMA_TOOL } from "../bridge/reserved.ts";
+import type { EvalStatusEvent, ExecuteTool } from "../tool/types.ts";
+import { type AgentExecuteTool, runEvalAgent } from "./agent-bridge.ts";
+import { type MarshalledToolResult, type OutputExecuteTool, runEvalOutput } from "./output-bridge.ts";
+import { type EvalSchemaToolInfo, runEvalSchema } from "./schema-bridge.ts";
+
+export interface ReservedDispatchContext {
+	readonly callId: string;
+	readonly args: unknown;
+	readonly executeTool: AgentExecuteTool & OutputExecuteTool & ExecuteTool;
+	readonly taskToolName: string;
+	readonly taskOutputToolName: string;
+	readonly listTools: (() => readonly EvalSchemaToolInfo[]) | undefined;
+	readonly signal: AbortSignal | undefined;
+	readonly emitStatus: (event: EvalStatusEvent) => void;
+	readonly marshalToolResult: (result: AgentToolResult<unknown>) => MarshalledToolResult;
+}
+
+class SchemaUnavailableError extends Error {
+	readonly name = "SchemaUnavailableError";
+
+	constructor() {
+		super("tool_schema() unavailable: this session does not expose a tool catalog");
+	}
+}
+
+export function isReservedToolName(toolName: string): boolean {
+	return toolName === RESERVED_AGENT_TOOL || toolName === RESERVED_OUTPUT_TOOL || toolName === RESERVED_SCHEMA_TOOL;
+}
+
+export async function runReservedTool(toolName: string, context: ReservedDispatchContext): Promise<unknown> {
+	if (toolName === RESERVED_AGENT_TOOL) {
+		return await runEvalAgent(context.args, {
+			callId: context.callId,
+			taskToolName: context.taskToolName,
+			executeTool: context.executeTool,
+			...(context.signal === undefined ? {} : { signal: context.signal }),
+			emitStatus: context.emitStatus,
+		});
+	}
+	if (toolName === RESERVED_OUTPUT_TOOL) {
+		return await runEvalOutput(context.args, {
+			taskOutputToolName: context.taskOutputToolName,
+			executeTool: context.executeTool,
+			...(context.signal === undefined ? {} : { signal: context.signal }),
+			marshalToolResult: context.marshalToolResult,
+		});
+	}
+	if (toolName === RESERVED_SCHEMA_TOOL) {
+		const listTools = context.listTools;
+		if (listTools === undefined) throw new SchemaUnavailableError();
+		return runEvalSchema(context.args, { listTools });
+	}
+	throw new Error(`runReservedTool received a non-reserved tool name: ${toolName}`);
+}

package/src/bridges/schema-bridge.ts

@@ -0,0 +1,69 @@
+import { type Static, Type } from "typebox";
+import { Check, Errors } from "typebox/value";
+
+const schemaArgsSchema = Type.Object(
+	{ name: Type.Optional(Type.String({ minLength: 1 })) },
+	{ additionalProperties: false },
+);
+
+type SchemaArgs = Static<typeof schemaArgsSchema>;
+
+export interface EvalSchemaToolInfo {
+	readonly name: string;
+	readonly description?: string | undefined;
+	readonly parameters?: unknown;
+}
+
+export interface RunEvalSchemaOptions {
+	readonly listTools: () => readonly EvalSchemaToolInfo[];
+}
+
+export type EvalSchemaResult =
+	| { readonly tools: readonly string[] }
+	| { readonly name: string; readonly description: string | undefined; readonly parameters: unknown };
+
+class SchemaArgumentsError extends Error {
+	readonly name = "SchemaArgumentsError";
+
+	constructor(summary: string) {
+		super(`schema() received invalid arguments: ${summary}`);
+	}
+}
+
+class SchemaUnknownToolError extends Error {
+	readonly name = "SchemaUnknownToolError";
+
+	constructor(requested: string, suggestions: readonly string[]) {
+		const hint = suggestions.length > 0 ? ` Did you mean: ${suggestions.join(", ")}?` : "";
+		super(`schema() found no tool named "${requested}".${hint}`);
+	}
+}
+
+export function runEvalSchema(args: unknown, options: RunEvalSchemaOptions): EvalSchemaResult {
+	const parsed = parseSchemaArgs(args);
+	const tools = options.listTools();
+	if (parsed.name === undefined) return { tools: tools.map((tool) => tool.name) };
+
+	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));
+}
+
+function parseSchemaArgs(value: unknown): SchemaArgs {
+	if (Check(schemaArgsSchema, value)) return value;
+	const summary = Errors(schemaArgsSchema, value)
+		.map((error) => `${error.instancePath || "/"} ${error.message}`)
+		.join("; ");
+	throw new SchemaArgumentsError(summary || "invalid value");
+}
+
+function nearestNames(requested: string, tools: readonly EvalSchemaToolInfo[]): readonly string[] {
+	const needle = requested.toLowerCase();
+	return tools
+		.map((tool) => tool.name)
+		.filter((name) => {
+			const candidate = name.toLowerCase();
+			return candidate.includes(needle) || needle.includes(candidate);
+		})
+		.slice(0, 5);
+}

package/src/bridges/schema-hint.ts

@@ -0,0 +1,140 @@
+const SCHEMA_HINT_MAX_CHARS = 1_200;
+const SCHEMA_HINT_MAX_PROPERTIES = 30;
+const DESCRIPTION_MAX_CHARS = 80;
+const ENUM_MAX_VALUES = 8;
+const NESTED_MAX_DEPTH = 2;
+const HINT_HEADER = "Expected parameters:";
+
+interface SchemaLike {
+	readonly type?: unknown;
+	readonly properties?: unknown;
+	readonly required?: unknown;
+	readonly items?: unknown;
+	readonly description?: unknown;
+	readonly enum?: unknown;
+	readonly const?: unknown;
+	readonly oneOf?: unknown;
+	readonly anyOf?: unknown;
+	readonly allOf?: unknown;
+}
+
+export function appendSchemaHint(message: string, toolName: string, schema: unknown): string {
+	const rendered = renderSchemaHint(toolName, schema);
+	if (rendered === undefined) return message;
+	return `${message}\n\n${HINT_HEADER}\n${rendered}`;
+}
+
+export function renderSchemaHint(toolName: string, schema: unknown): string | undefined {
+	if (!isSchemaLike(schema)) return undefined;
+	const lines = renderObjectLines(schema, 0, 1);
+	if (lines.length === 0) return undefined;
+	return fitLines(lines, `[truncated; call tool_schema(${JSON.stringify(toolName)}) for the full schema]`);
+}
+
+function renderObjectLines(schema: SchemaLike, indent: number, depth: number): readonly string[] {
+	const required = stringArray(schema.required);
+	const entries = propertyEntries(schema.properties);
+	if (entries.length === 0 && required.length === 0) return [];
+
+	const ordered = [
+		...entries.filter(([name]) => required.includes(name)),
+		...entries.filter(([name]) => !required.includes(name)),
+	];
+	const pad = "  ".repeat(indent + 1);
+	const lines: string[] = [];
+	if (indent === 0 && required.length > 0) lines.push(`required: ${required.join(", ")}`);
+
+	const shown = ordered.slice(0, SCHEMA_HINT_MAX_PROPERTIES);
+	for (const [name, value] of shown) {
+		lines.push(`${pad}${name}${required.includes(name) ? "" : "?"}: ${describeProperty(value)}`);
+		lines.push(...nestedLines(value, indent, depth));
+	}
+	const hidden = ordered.length - shown.length;
+	if (hidden > 0) lines.push(`${pad}… ${hidden} more propert${hidden === 1 ? "y" : "ies"}`);
+	return lines;
+}
+
+function nestedLines(value: unknown, indent: number, depth: number): readonly string[] {
+	if (depth >= NESTED_MAX_DEPTH || !isSchemaLike(value)) return [];
+	const nested = isSchemaLike(value.items) ? value.items : value;
+	if (propertyEntries(nested.properties).length === 0) return [];
+	return renderObjectLines(nested, indent + 1, depth + 1);
+}
+
+function describeProperty(value: unknown): string {
+	if (!isSchemaLike(value)) return "unknown";
+	const parts = [typeLabel(value)];
+	const description = firstLine(value.description);
+	if (description !== undefined) parts.push(`— ${truncate(description, DESCRIPTION_MAX_CHARS)}`);
+	return parts.join(" ");
+}
+
+function typeLabel(schema: SchemaLike): string {
+	if (Object.hasOwn(schema, "const")) return JSON.stringify(schema.const);
+	const enumValues = schema.enum;
+	if (Array.isArray(enumValues) && enumValues.length > 0) return unionLabel(enumValues.map(literal));
+	const branches = schema.oneOf ?? schema.anyOf;
+	if (Array.isArray(branches) && branches.length > 0) return unionLabel(branches.map(branchLabel));
+	if (Array.isArray(schema.allOf) && schema.allOf.length > 0) return branchLabel(schema.allOf[0]);
+
+	const type = schema.type;
+	const base = typeof type === "string" ? type : Array.isArray(type) ? type.filter(isString).join("|") : "unknown";
+	if (base !== "array") return base;
+	return isSchemaLike(schema.items) ? `array<${typeLabel(schema.items)}>` : "array";
+}
+
+function unionLabel(values: readonly string[]): string {
+	const shown = values.slice(0, ENUM_MAX_VALUES).join(" | ");
+	return values.length > ENUM_MAX_VALUES ? `${shown} | … (${values.length - ENUM_MAX_VALUES} more)` : shown;
+}
+
+function branchLabel(value: unknown): string {
+	return isSchemaLike(value) ? typeLabel(value) : "unknown";
+}
+
+function literal(value: unknown): string {
+	return JSON.stringify(value) ?? String(value);
+}
+
+function fitLines(lines: readonly string[], marker: string): string {
+	const budget = SCHEMA_HINT_MAX_CHARS - HINT_HEADER.length - 1;
+	const kept: string[] = [];
+	let used = 0;
+	for (const line of lines) {
+		const next = used + line.length + (kept.length === 0 ? 0 : 1);
+		if (next > budget - marker.length - 1) {
+			kept.push(marker);
+			return kept.join("\n");
+		}
+		kept.push(line);
+		used = next;
+	}
+	return kept.join("\n");
+}
+
+function propertyEntries(properties: unknown): readonly (readonly [string, unknown])[] {
+	if (typeof properties !== "object" || properties === null || Array.isArray(properties)) return [];
+	return Object.entries(properties);
+}
+
+function stringArray(value: unknown): readonly string[] {
+	return Array.isArray(value) ? value.filter(isString) : [];
+}
+
+function firstLine(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const line = value.split("\n", 1)[0]?.trim();
+	return line === undefined || line.length === 0 ? undefined : line;
+}
+
+function truncate(value: string, maxChars: number): string {
+	return value.length <= maxChars ? value : `${value.slice(0, maxChars)}…`;
+}
+
+function isSchemaLike(value: unknown): value is SchemaLike {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isString(value: unknown): value is string {
+	return typeof value === "string";
+}

package/src/extension/runtime-factory.ts

@@ -87,8 +87,10 @@ export async function createRuntime(
 }
 
 export function createExecuteTool(pi: CodemodeRuntimeAPI, activeTools?: ReadonlySet<string>): AgentExecuteTool {
+	// A cell names tools directly and cannot run tool_search first, so eval opts in to
+	// lazy activation. Eligibility still belongs to the extension that registered the tool.
 	const executeTool: AgentExecuteTool = (toolName, params, executeOptions) =>
-		pi.executeTool(toolName, params, executeOptions);
+		pi.executeTool(toolName, params, { ...executeOptions, activateInactiveTool: true });
 	return Object.assign(executeTool, {
 		isToolAvailable: (name: string): boolean => activeTools?.has(name) ?? pi.getActiveTools().includes(name),
 	});

package/src/index.ts

@@ -1,6 +1,7 @@
 import * as os from "node:os";
 import type { ExtensionContext } from "@code-yeongyu/senpi";
 import type { AgentExecuteTool } from "./bridges/agent-bridge.ts";
+import type { EvalSchemaToolInfo } from "./bridges/schema-bridge.ts";
 import { type CompletionRequest, type CompletionResult, createCompletionHandler } from "./completion/handler.ts";
 import { defaultCodemodeSettings } from "./config/settings.ts";
 import { EvalNotifier } from "./extension/eval-notifier.ts";
@@ -33,6 +34,7 @@ export interface CodemodeExtensionAPI {
 	on(event: CodemodeEvent, handler: (event: unknown, ctx: ExtensionContext) => Promise<void> | void): void;
 	executeTool: AgentExecuteTool;
 	getActiveTools(): string[];
+	getAllTools(): readonly EvalSchemaToolInfo[];
 	sendUserMessage(content: string, options?: { deliverAs?: "steer" | "followUp" }): void;
 }
 
@@ -67,6 +69,7 @@ export default function senpiCodemode(pi: CodemodeExtensionAPI, options: SenpiCo
 				kernelManager: manager,
 				cellTimeoutSeconds: runtime.settings.cellTimeoutSeconds,
 				executeTool: runtime.executeTool,
+				listTools: () => pi.getAllTools(),
 				complete,
 				settings: runtime.settings,
 				artifactsDir: runtime.artifactsDir,
@@ -95,6 +98,7 @@ export default function senpiCodemode(pi: CodemodeExtensionAPI, options: SenpiCo
 			kernelManager: manager,
 			cellTimeoutSeconds: defaultCodemodeSettings.cellTimeoutSeconds,
 			executeTool: createExecuteTool(pi),
+			listTools: () => pi.getAllTools(),
 			complete,
 			settings: defaultCodemodeSettings,
 			cellManager: new EvalDetachedCellManager({ notifier }),

package/src/kernels/jl/prelude.jl

@@ -194,6 +194,12 @@ function completion(prompt::AbstractString; model="default", system=nothing, sch
     get(response, "text", response)
 end
 
+function tool_schema(name=nothing)
+    arguments = Dict{String, Any}()
+    name !== nothing && (arguments["name"] = string(name))
+    senpi_with_bridge_timeout_pause(() -> senpi_call_tool("__schema__", arguments))
+end
+
 function output(ids...; format="raw", offset=nothing, limit=nothing)
     isempty(ids) && error("At least one output ID is required")
     format in ("raw", "tail") || error("output() format must be 'raw' or 'tail'")

package/src/kernels/js/local-module-loader.ts

@@ -4,6 +4,7 @@ import type { BridgeConnectionConfig } from "../../bridge/protocol.ts";
 import {
 	RESERVED_AGENT_TOOL,
 	RESERVED_OUTPUT_TOOL,
+	RESERVED_SCHEMA_TOOL,
 	TIMEOUT_PAUSE_OP,
 	TIMEOUT_RESUME_OP,
 } from "../../bridge/reserved.ts";
@@ -33,6 +34,7 @@ type RuntimeModuleContext = {
 	readonly cwdUrl: string;
 	readonly localRootUrls: Readonly<Record<string, string>>;
 	readonly reservedAgentTool: string;
+	readonly reservedSchemaTool: string;
 	readonly reservedOutputTool: string;
 	readonly timeoutPauseOp: string;
 	readonly timeoutResumeOp: string;
@@ -55,6 +57,7 @@ function runtimeContext(options: LocalModuleLoaderOptions): RuntimeModuleContext
 		localRootUrls: roots,
 		reservedAgentTool: RESERVED_AGENT_TOOL,
 		reservedOutputTool: RESERVED_OUTPUT_TOOL,
+		reservedSchemaTool: RESERVED_SCHEMA_TOOL,
 		timeoutPauseOp: TIMEOUT_PAUSE_OP,
 		timeoutResumeOp: TIMEOUT_RESUME_OP,
 	};
@@ -66,6 +69,7 @@ function loaderPrelude(context: RuntimeModuleContext): string {
 		`globalThis.__senpi_module_context__ = ${serialized};`,
 		"globalThis.__senpi_reserved_agent_tool__ = globalThis.__senpi_module_context__.reservedAgentTool;",
 		"globalThis.__senpi_reserved_output_tool__ = globalThis.__senpi_module_context__.reservedOutputTool;",
+		"globalThis.__senpi_reserved_schema_tool__ = globalThis.__senpi_module_context__.reservedSchemaTool;",
 		"globalThis.__senpi_timeout_pause_op__ = globalThis.__senpi_module_context__.timeoutPauseOp;",
 		"globalThis.__senpi_timeout_resume_op__ = globalThis.__senpi_module_context__.timeoutResumeOp;",
 		"globalThis.__senpi_import__ = async (source, options) => {",

package/src/kernels/js/worker-runtime.js

@@ -50,6 +50,7 @@ export class JsWorkerRuntime {
 		globalThis.read = async (path, options, ...rest) => await this.#read(path, helperOptions("read", options, rest));
 		globalThis.write = async (path, content) => await this.#write(path, content);
 		globalThis.output = async (...args) => await this.#output(args);
+		globalThis.tool_schema = async name => await this.#toolSchema(name);
 		globalThis.agent = async (prompt, options, ...rest) => await this.#agent(prompt, options, rest);
 		globalThis.parallel = async thunks => await this.#parallel(thunks);
 		globalThis.pipeline = async (items, ...stages) => await this.#pipeline(items, stages);
@@ -250,6 +251,11 @@ export class JsWorkerRuntime {
 		return node;
 	}
 
+	async #toolSchema(name) {
+		const args = name === undefined || name === null ? {} : { name: String(name) };
+		return await this.#callTool(reservedTool("__senpi_reserved_schema_tool__", "tool_schema"), args);
+	}
+
 	async #callTool(toolName, args) {
 		const hooks = this.#hooks;
 		if (!hooks) throw new Error("tool call outside active JS cell");

package/src/kernels/py/prelude.py

@@ -37,6 +37,7 @@ EMIT_LOCK = Lock()
 # Mirrors src/bridge/reserved.ts; this standalone subprocess asset cannot import TypeScript.
 RESERVED_AGENT_TOOL = "__agent__"
 RESERVED_OUTPUT_TOOL = "__output__"
+RESERVED_SCHEMA_TOOL = "__schema__"
 TIMEOUT_PAUSE_OP = "timeout-pause"
 TIMEOUT_RESUME_OP = "timeout-resume"
 
@@ -374,6 +375,14 @@ def completion(
     return response.get("text", response)
 
 
+def tool_schema(name: str | None = None) -> Any:
+    args: dict[str, Any] = {} if name is None else {"name": name}
+    return bridge_post(
+        "/call",
+        {"callId": f"py-{uuid.uuid4()}", "toolName": RESERVED_SCHEMA_TOOL, "args": args},
+    )
+
+
 def output(
     *ids: str,
     format: str = "raw",
@@ -844,6 +853,7 @@ USER_NS.update(
         "completion": completion,
         "agent": agent,
         "output": output,
+        "tool_schema": tool_schema,
         "__senpi_magic": _magic,
         "__senpi_magic_cell": _magic_cell,
         "__senpi_shell": _shell,

package/src/kernels/rb/prelude.rb

@@ -5,6 +5,7 @@ require "uri"
 
 SENPI_RESERVED_AGENT_TOOL = "__agent__"
 SENPI_RESERVED_OUTPUT_TOOL = "__output__"
+SENPI_RESERVED_SCHEMA_TOOL = "__schema__"
 SENPI_INTERNAL_URL = Regexp.new("\\A([a-z][a-z0-9+.\\-]*)://(.*)\\z", Regexp::IGNORECASE)
 
 def __senpi_status_enabled?
@@ -187,6 +188,11 @@ def completion(prompt, model: "default", system: nil, schema: nil, **kwargs)
   result.fetch("text", result)
 end
 
+def tool_schema(name = nil)
+  args = name.nil? ? {} : { "name" => name.to_s }
+  __senpi_call_tool(SENPI_RESERVED_SCHEMA_TOOL, args)
+end
+
 def output(*ids, format: "raw", offset: nil, limit: nil)
   raise ArgumentError, "At least one output ID is required" if ids.empty?
   raise ArgumentError, "output() format must be 'raw' or 'tail'" unless ["raw", "tail"].include?(format)

package/src/prompt/eval-prompt.ts

@@ -154,6 +154,11 @@ env(key?=None, value?=None) → str | None | dict
     Task/agent output by id. Reads immediately: running tasks return their status; \`format\` selects full (\`"raw"\`) or trailing (\`"tail"\`) output.
 {{/if}}tool.<name>(args) → unknown
     Invoke any session tool; \`args\` = its parameter object.
+tool_schema(name?) → dict
+    Parameter schema of a tool without calling it; omit \`name\` to list tool names.
+    Use it before calling a tool you have not called before — a failed call also
+    returns the expected parameters, so fix the args and retry in the next cell
+    instead of abandoning eval.
 completion(prompt, model?="default", system?=None, schema?=None) → str | dict
     Oneshot, stateless (no history/tools). \`model\`: \`"smol"\` fast | \`"default"\` session | \`"slow"\` most capable. \`schema\` (JSON-Schema) → structured output, parsed object.
 {{#if spawns}}agent(prompt, agent?="{{spawnDefaultAgent}}", model?=None, label?=None, schema?=None, handle?=False) → str | dict

package/src/tool/cell-handler.ts

@@ -1,8 +1,9 @@
 import type { AgentToolResult, AgentToolUpdateCallback, ExtensionContext } from "@code-yeongyu/senpi";
 import type { KernelToHostMessage } from "../bridge/protocol.ts";
-import { RESERVED_AGENT_TOOL, RESERVED_OUTPUT_TOOL } from "../bridge/reserved.ts";
-import { type AgentExecuteTool, runEvalAgent } from "../bridges/agent-bridge.ts";
-import { runEvalOutput } from "../bridges/output-bridge.ts";
+import type { AgentExecuteTool } from "../bridges/agent-bridge.ts";
+import { isReservedToolName, runReservedTool } from "../bridges/reserved-dispatch.ts";
+import type { EvalSchemaToolInfo } from "../bridges/schema-bridge.ts";
+import { appendSchemaHint } from "../bridges/schema-hint.ts";
 import type { CompletionRequest, CompletionResult } from "../completion/handler.ts";
 import { handleCompletionToolCall } from "../completion/tool-bridge.ts";
 import type { ResolvedCodemodeSettings } from "../config/settings.ts";
@@ -36,6 +37,7 @@ export interface CellState {
 
 export interface CellBridgeRuntime {
 	readonly executeTool: AgentExecuteTool;
+	readonly listTools?: () => readonly EvalSchemaToolInfo[];
 	readonly settings: ResolvedCodemodeSettings;
 	readonly complete?: (request: CompletionRequest, ctx: ExtensionContext) => Promise<CompletionResult>;
 	readonly ctx: ExtensionContext;
@@ -151,25 +153,17 @@ export class CellHandler {
 			});
 			return;
 		}
-		if (message.toolName === RESERVED_AGENT_TOOL) {
+		if (isReservedToolName(message.toolName)) {
 			await this.#deliverToolReply(message, async () => ({
-				value: await runEvalAgent(message.args, {
+				value: await runReservedTool(message.toolName, {
 					callId: message.callId,
-					taskToolName: this.#runtime.settings.taskTools.task,
+					args: message.args,
 					executeTool: this.#runtime.executeTool,
-					signal: this.#state.signal,
-					emitStatus: (event) => this.#recordStatus(event),
-				}),
-				toolCallOk: true,
-			}));
-			return;
-		}
-		if (message.toolName === RESERVED_OUTPUT_TOOL) {
-			await this.#deliverToolReply(message, async () => ({
-				value: await runEvalOutput(message.args, {
+					taskToolName: this.#runtime.settings.taskTools.task,
 					taskOutputToolName: this.#runtime.settings.taskTools.output,
-					executeTool: this.#runtime.executeTool,
+					listTools: this.#runtime.listTools,
 					signal: this.#state.signal,
+					emitStatus: (event) => this.#recordStatus(event),
 					marshalToolResult,
 				}),
 				toolCallOk: true,
@@ -210,7 +204,11 @@ export class CellHandler {
 			this.#kernel.deliverToolReply({ type: "tool-reply", callId: message.callId, ok: true, value: reply.value });
 		} catch (error) {
 			if (!this.#state.active) return;
-			const text = error instanceof Error ? error.message : String(error);
+			const text = appendSchemaHint(
+				error instanceof Error ? error.message : String(error),
+				message.toolName,
+				this.#toolParameters(message.toolName),
+			);
 			this.#state.toolCalls.push({ name: message.toolName, ok: false, error: text });
 			this.#kernel.deliverToolReply({
 				type: "tool-reply",
@@ -222,6 +220,10 @@ export class CellHandler {
 		this.#emitUpdate(false);
 	}
 
+	#toolParameters(toolName: string): unknown {
+		return this.#runtime.listTools?.().find((tool) => tool.name === toolName)?.parameters;
+	}
+
 	#recordStatus(event: EvalStatusEvent): void {
 		if (!this.#runtime.settings.statusEvents) return;
 		upsertStatusEvent(this.#state.statusEvents, event);

package/src/tool/eval-tool.ts

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 import type { AgentToolResult, AgentToolUpdateCallback, ExtensionContext, ToolDefinition } from "@code-yeongyu/senpi";
+import type { EvalSchemaToolInfo } from "../bridges/schema-bridge.ts";
 import type { CompletionRequest, CompletionResult } from "../completion/handler.ts";
 import { defaultCodemodeSettings, type ResolvedCodemodeSettings } from "../config/settings.ts";
 import type { EvalExecutionTracker } from "../extension/session-manager.ts";
@@ -37,6 +38,7 @@ export interface CreateEvalToolOptions {
 	readonly kernelManager: EvalKernelManager;
 	readonly cellTimeoutSeconds: number;
 	readonly executeTool: ExecuteTool;
+	readonly listTools?: () => readonly EvalSchemaToolInfo[];
 	readonly complete?: (request: CompletionRequest, ctx: ExtensionContext) => Promise<CompletionResult>;
 	readonly settings?: ResolvedCodemodeSettings;
 	readonly artifactsDir?: string;
@@ -351,6 +353,7 @@ async function executeCell(
 		execution.setKernel(kernel);
 		handler = new CellHandler(kernel, state, {
 			executeTool: options.executeTool,
+			...(options.listTools === undefined ? {} : { listTools: options.listTools }),
 			settings: options.settings ?? defaultCodemodeSettings,
 			...(options.complete === undefined ? {} : { complete: options.complete }),
 			ctx: bridgeContext,

package/src/tool/types.ts

@@ -110,7 +110,7 @@ export interface EvalKernelManager {
 export type ExecuteTool = (
 	toolName: string,
 	params: unknown,
-	options?: { signal?: AbortSignal; onUpdate?: AgentToolUpdateCallback<unknown> },
+	options?: { signal?: AbortSignal; onUpdate?: AgentToolUpdateCallback<unknown>; activateInactiveTool?: boolean },
 ) => Promise<AgentToolResult<unknown>>;
 
 export interface EvalToolCallSummary {