@oh-my-pi/pi-coding-agent 14.3.0 → 14.4.0

package/src/tools/ast-grep.ts

@@ -15,7 +15,6 @@ import { createFileRecorder, formatResultPath } from "./file-recorder";
 import { formatMatchLine } from "./match-line-format";
 import type { OutputMeta } from "./output-meta";
 import {
-	combineSearchGlobs,
 	hasGlobPathChars,
 	normalizePathLikeInput,
 	parseSearchPath,
@@ -24,6 +23,7 @@ import {
 } from "./path-utils";
 import {
 	dedupeParseErrors,
+	formatCodeFrameLine,
 	formatCount,
 	formatEmptyMessage,
 	formatErrorMessage,
@@ -35,14 +35,12 @@ import { ToolError } from "./tool-errors";
 import { toolResult } from "./tool-result";
 
 const astGrepSchema = Type.Object({
-	pat: Type.Array(Type.String(), { minItems: 1, description: "AST patterns to match" }),
-	lang: Type.Optional(Type.String({ description: "Language override" })),
-	path: Type.Optional(Type.String({ description: "File, directory, or glob pattern to search (default: cwd)" })),
-	glob: Type.Optional(Type.String({ description: "Optional glob filter relative to path" })),
-	sel: Type.Optional(Type.String({ description: "Optional selector for contextual pattern mode" })),
-	limit: Type.Optional(Type.Number({ description: "Max matches", default: 50 })),
-	offset: Type.Optional(Type.Number({ description: "Skip first N matches", default: 0 })),
-	context: Type.Optional(Type.Number({ description: "Context lines around each match" })),
+	pat: Type.String({ description: "ast pattern", examples: ["console.log($$$)"] }),
+	path: Type.String({
+		description: "file, directory, glob, or comma-separated paths to search",
+		examples: ["src/", "src/foo.ts", "src/**/*.ts"],
+	}),
+	skip: Type.Optional(Type.Number({ description: "matches to skip", default: 0 })),
 });
 
 export interface AstGrepToolDetails {
@@ -55,6 +53,9 @@ export interface AstGrepToolDetails {
 	files?: string[];
 	fileMatches?: Array<{ path: string; count: number }>;
 	meta?: OutputMeta;
+	/** Pre-formatted text for the user-visible TUI render. Mirrors `result.text` lines but uses
+	 * a `│` gutter and `*` to mark match lines. The TUI uses this directly so it never parses model-facing text. */
+	displayContent?: string;
 }
 
 export class AstGrepTool implements AgentTool<typeof astGrepSchema, AstGrepToolDetails> {
@@ -76,55 +77,48 @@ export class AstGrepTool implements AgentTool<typeof astGrepSchema, AstGrepToolD
 		_context?: AgentToolContext,
 	): Promise<AgentToolResult<AstGrepToolDetails>> {
 		return untilAborted(signal, async () => {
-			const patterns = [...new Set(params.pat.map(pattern => pattern.trim()).filter(pattern => pattern.length > 0))];
-			if (patterns.length === 0) {
-				throw new ToolError("`pat` must include at least one non-empty pattern");
+			const pattern = params.pat.trim();
+			if (pattern.length === 0) {
+				throw new ToolError("`pat` must be a non-empty pattern");
 			}
-			const limit = params.limit === undefined ? 50 : Math.floor(params.limit);
-			if (!Number.isFinite(limit) || limit < 1) {
-				throw new ToolError("Limit must be a positive number");
+			const patterns = [pattern];
+			const skip = params.skip === undefined ? 0 : Math.floor(params.skip);
+			if (!Number.isFinite(skip) || skip < 0) {
+				throw new ToolError("skip must be a non-negative number");
 			}
-			const offset = params.offset === undefined ? 0 : Math.floor(params.offset);
-			if (!Number.isFinite(offset) || offset < 0) {
-				throw new ToolError("Offset must be a non-negative number");
-			}
-			const context = params.context === undefined ? undefined : Math.floor(params.context);
-			if (context !== undefined && (!Number.isFinite(context) || context < 0)) {
-				throw new ToolError("Context must be a non-negative number");
-			}
-
 			const formatScopePath = (targetPath: string): string => {
 				const relative = path.relative(this.session.cwd, targetPath).replace(/\\/g, "/");
 				return relative.length === 0 ? "." : relative;
 			};
 			let searchPath: string | undefined;
 			let scopePath: string | undefined;
-			let globFilter = params.glob ? normalizePathLikeInput(params.glob) || undefined : undefined;
-			const rawPath = params.path ? normalizePathLikeInput(params.path) || undefined : undefined;
-			if (rawPath) {
-				const internalRouter = this.session.internalRouter;
-				if (internalRouter?.canHandle(rawPath)) {
-					if (hasGlobPathChars(rawPath)) {
-						throw new ToolError(`Glob patterns are not supported for internal URLs: ${rawPath}`);
-					}
-					const resource = await internalRouter.resolve(rawPath);
-					if (!resource.sourcePath) {
-						throw new ToolError(`Cannot search internal URL without backing file: ${rawPath}`);
-					}
-					searchPath = resource.sourcePath;
-					scopePath = formatScopePath(searchPath);
+			let globFilter: string | undefined;
+			const rawPath = normalizePathLikeInput(params.path);
+			if (rawPath.length === 0) {
+				throw new ToolError("`path` must be a non-empty path or glob");
+			}
+			const internalRouter = this.session.internalRouter;
+			if (internalRouter?.canHandle(rawPath)) {
+				if (hasGlobPathChars(rawPath)) {
+					throw new ToolError(`Glob patterns are not supported for internal URLs: ${rawPath}`);
+				}
+				const resource = await internalRouter.resolve(rawPath);
+				if (!resource.sourcePath) {
+					throw new ToolError(`Cannot search internal URL without backing file: ${rawPath}`);
+				}
+				searchPath = resource.sourcePath;
+				scopePath = formatScopePath(searchPath);
+			} else {
+				const multiSearchPath = await resolveMultiSearchPath(rawPath, this.session.cwd, globFilter);
+				if (multiSearchPath) {
+					searchPath = multiSearchPath.basePath;
+					globFilter = multiSearchPath.glob;
+					scopePath = multiSearchPath.scopePath;
 				} else {
-					const multiSearchPath = await resolveMultiSearchPath(rawPath, this.session.cwd, globFilter);
-					if (multiSearchPath) {
-						searchPath = multiSearchPath.basePath;
-						globFilter = multiSearchPath.glob;
-						scopePath = multiSearchPath.scopePath;
-					} else {
-						const parsedPath = parseSearchPath(rawPath);
-						searchPath = resolveToCwd(parsedPath.basePath, this.session.cwd);
-						globFilter = combineSearchGlobs(parsedPath.glob, globFilter);
-						scopePath = formatScopePath(searchPath);
-					}
+					const parsedPath = parseSearchPath(rawPath);
+					searchPath = resolveToCwd(parsedPath.basePath, this.session.cwd);
+					globFilter = parsedPath.glob;
+					scopePath = formatScopePath(searchPath);
 				}
 			}
 
@@ -140,13 +134,9 @@ export class AstGrepTool implements AgentTool<typeof astGrepSchema, AstGrepToolD
 
 			const result = await astGrep({
 				patterns,
-				lang: params.lang?.trim(),
 				path: resolvedSearchPath,
 				glob: globFilter,
-				selector: params.sel?.trim(),
-				limit,
-				offset,
-				context,
+				offset: skip,
 				includeMeta: true,
 				signal,
 			});
@@ -183,7 +173,7 @@ export class AstGrepTool implements AgentTool<typeof astGrepSchema, AstGrepToolD
 
 			if (result.matches.length === 0) {
 				const noMatchMessage = dedupedParseErrors.length
-					? "No matches found. Parse issues mean the query may be mis-scoped; narrow `path`/`glob` or set `lang` before concluding absence."
+					? "No matches found. Parse issues mean the query may be mis-scoped; narrow `path` before concluding absence."
 					: "No matches found";
 				const parseMessage = dedupedParseErrors.length
 					? `\n${formatParseErrors(dedupedParseErrors).join("\n")}`
@@ -193,16 +183,22 @@ export class AstGrepTool implements AgentTool<typeof astGrepSchema, AstGrepToolD
 
 			const useHashLines = resolveFileDisplayMode(this.session).hashLines;
 			const outputLines: string[] = [];
+			const displayLines: string[] = [];
 			const renderMatchesForFile = (relativePath: string) => {
 				const fileMatches = matchesByFile.get(relativePath) ?? [];
+				const lineNumberWidth = fileMatches.reduce((width, match) => {
+					const lineCount = match.text.split("\n").length;
+					const endLine = match.startLine + lineCount - 1;
+					return Math.max(width, String(match.startLine).length, String(endLine).length);
+				}, 0);
 				for (const match of fileMatches) {
 					const matchLines = match.text.split("\n");
-					const lineNumbers = matchLines.map((_, index) => match.startLine + index);
-					const lineWidth = Math.max(...lineNumbers.map(value => value.toString().length));
-					const formatLine = (lineNumber: number, line: string, isMatch: boolean): string =>
-						formatMatchLine(lineNumber, line, isMatch, { useHashLines, lineWidth });
 					for (let index = 0; index < matchLines.length; index++) {
-						outputLines.push(formatLine(match.startLine + index, matchLines[index], index === 0));
+						const lineNumber = match.startLine + index;
+						const isMatch = index === 0;
+						const line = matchLines[index] ?? "";
+						outputLines.push(formatMatchLine(lineNumber, line, isMatch, { useHashLines }));
+						displayLines.push(formatCodeFrameLine(isMatch ? "*" : " ", lineNumber, line, lineNumberWidth));
 					}
 					if (match.metaVariables && Object.keys(match.metaVariables).length > 0) {
 						const serializedMeta = Object.entries(match.metaVariables)
@@ -210,6 +206,7 @@ export class AstGrepTool implements AgentTool<typeof astGrepSchema, AstGrepToolD
 							.map(([key, value]) => `${key}=${value}`)
 							.join(", ");
 						outputLines.push(`  meta: ${serializedMeta}`);
+						displayLines.push(`  meta: ${serializedMeta}`);
 					}
 					fileMatchCounts.set(relativePath, (fileMatchCounts.get(relativePath) ?? 0) + 1);
 				}
@@ -229,18 +226,26 @@ export class AstGrepTool implements AgentTool<typeof astGrepSchema, AstGrepToolD
 						for (const relativePath of directoryFiles) {
 							if (outputLines.length > 0) {
 								outputLines.push("");
+								displayLines.push("");
 							}
-							outputLines.push(`# ${path.basename(relativePath)}`);
+							const header = `# ${path.basename(relativePath)}`;
+							outputLines.push(header);
+							displayLines.push(header);
 							renderMatchesForFile(relativePath);
 						}
 						continue;
 					}
 					if (outputLines.length > 0) {
 						outputLines.push("");
+						displayLines.push("");
 					}
-					outputLines.push(`# ${directory}`);
+					const dirHeader = `# ${directory}`;
+					outputLines.push(dirHeader);
+					displayLines.push(dirHeader);
 					for (const relativePath of directoryFiles) {
-						outputLines.push(`## └─ ${path.basename(relativePath)}`);
+						const fileHeader = `## └─ ${path.basename(relativePath)}`;
+						outputLines.push(fileHeader);
+						displayLines.push(fileHeader);
 						renderMatchesForFile(relativePath);
 					}
 				}
@@ -256,6 +261,7 @@ export class AstGrepTool implements AgentTool<typeof astGrepSchema, AstGrepToolD
 					path: filePath,
 					count: fileMatchCounts.get(filePath) ?? 0,
 				})),
+				displayContent: displayLines.join("\n"),
 			};
 			if (result.limitReached) {
 				outputLines.push("", "Result limit reached; narrow path pattern or increase limit.");
@@ -274,13 +280,9 @@ export class AstGrepTool implements AgentTool<typeof astGrepSchema, AstGrepToolD
 // =============================================================================
 
 interface AstGrepRenderArgs {
-	pat?: string[];
-	lang?: string;
+	pat?: string;
 	path?: string;
-	sel?: string;
-	limit?: number;
-	offset?: number;
-	context?: number;
+	skip?: number;
 }
 
 const COLLAPSED_MATCH_LIMIT = PREVIEW_LIMITS.COLLAPSED_LINES * 2;
@@ -289,15 +291,10 @@ export const astGrepToolRenderer = {
 	inline: true,
 	renderCall(args: AstGrepRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component {
 		const meta: string[] = [];
-		if (args.lang) meta.push(`lang:${args.lang}`);
 		if (args.path) meta.push(`in ${args.path}`);
-		if (args.sel) meta.push("selector");
-		if (args.limit !== undefined && args.limit > 0) meta.push(`limit:${args.limit}`);
-		if (args.offset !== undefined && args.offset > 0) meta.push(`offset:${args.offset}`);
-		if (args.context !== undefined) meta.push(`context:${args.context}`);
-		if (args.pat && args.pat.length > 1) meta.push(`${args.pat.length} patterns`);
+		if (args.skip !== undefined && args.skip > 0) meta.push(`skip:${args.skip}`);
 
-		const description = args.pat?.length === 1 ? args.pat[0] : args.pat ? `${args.pat.length} patterns` : "?";
+		const description = args.pat ?? "?";
 		const text = renderStatusLine({ icon: "pending", title: "AST Grep", description, meta }, uiTheme);
 		return new Text(text, 0, 0);
 	},
@@ -321,19 +318,14 @@ export const astGrepToolRenderer = {
 		const limitReached = details?.limitReached ?? false;
 
 		if (matchCount === 0) {
-			const description = args?.pat?.length === 1 ? args.pat[0] : undefined;
+			const description = args?.pat;
 			const meta = ["0 matches"];
 			if (details?.scopePath) meta.push(`in ${details.scopePath}`);
 			if (filesSearched > 0) meta.push(`searched ${filesSearched}`);
 			const header = renderStatusLine({ icon: "warning", title: "AST Grep", description, meta }, uiTheme);
 			const lines = [header, formatEmptyMessage("No matches found", uiTheme)];
 			if (details?.parseErrors?.length) {
-				lines.push(
-					uiTheme.fg(
-						"warning",
-						"Query may be mis-scoped; narrow `path`/`glob` or set `lang` before concluding absence",
-					),
-				);
+				lines.push(uiTheme.fg("warning", "Query may be mis-scoped; narrow `path` before concluding absence"));
 				const capped = details.parseErrors.slice(0, PARSE_ERRORS_LIMIT);
 				for (const err of capped) {
 					lines.push(uiTheme.fg("warning", `  - ${err}`));
@@ -350,13 +342,13 @@ export const astGrepToolRenderer = {
 		if (details?.scopePath) meta.push(`in ${details.scopePath}`);
 		meta.push(`searched ${filesSearched}`);
 		if (limitReached) meta.push(uiTheme.fg("warning", "limit reached"));
-		const description = args?.pat?.length === 1 ? args.pat[0] : undefined;
+		const description = args?.pat;
 		const header = renderStatusLine(
 			{ icon: limitReached ? "warning" : "success", title: "AST Grep", description, meta },
 			uiTheme,
 		);
 
-		const textContent = result.content?.find(c => c.type === "text")?.text ?? "";
+		const textContent = result.details?.displayContent ?? result.content?.find(c => c.type === "text")?.text ?? "";
 		const rawLines = textContent.split("\n");
 		const hasSeparators = rawLines.some(line => line.trim().length === 0);
 		const allGroups: string[][] = [];

package/src/tools/bash.ts

@@ -42,20 +42,19 @@ async function saveBashOriginalArtifact(session: ToolSession, originalText: stri
 }
 
 const bashSchemaBase = Type.Object({
-	command: Type.String({ description: "Command to execute" }),
+	command: Type.String({ description: "command to execute", examples: ["ls -la", "echo hi"] }),
 	env: Type.Optional(
 		Type.Record(Type.String({ pattern: BASH_ENV_NAME_PATTERN.source }), Type.String(), {
-			description:
-				"Additional environment variables passed to the command and rendered inline as shell assignments; prefer this for multiline or quote-heavy content",
+			description: "extra env vars",
 		}),
 	),
-	timeout: Type.Optional(Type.Number({ description: "Timeout in seconds", default: 300 })),
-	cwd: Type.Optional(Type.String({ description: "Working directory (default: cwd)" })),
-	head: Type.Optional(Type.Number({ description: "Return only first N lines of output" })),
-	tail: Type.Optional(Type.Number({ description: "Return only last N lines of output" })),
+	timeout: Type.Optional(Type.Number({ description: "timeout in seconds", default: 300 })),
+	cwd: Type.Optional(Type.String({ description: "working directory", examples: ["src/", "/tmp"] })),
+	head: Type.Optional(Type.Number({ description: "first n lines of output" })),
+	tail: Type.Optional(Type.Number({ description: "last n lines of output" })),
 	pty: Type.Optional(
 		Type.Boolean({
-			description: "Run in PTY mode when command needs a real terminal (e.g. sudo/ssh/top/less); default: false",
+			description: "run in pty mode",
 		}),
 	),
 });
@@ -64,7 +63,7 @@ const bashSchemaWithAsync = Type.Object({
 	...bashSchemaBase.properties,
 	async: Type.Optional(
 		Type.Boolean({
-			description: "Run in background; returns immediately with a job ID. Result delivered as follow-up.",
+			description: "run in background",
 		}),
 	),
 });

package/src/tools/browser.ts

@@ -361,12 +361,12 @@ function resolvePageClient(page: Page): PuppeteerCdpClient | null {
 const puppeteerGetArgsSchema = Type.Array(
 	Type.Object({
 		selector: Type.String({
-			description:
-				"Selector for the target element (CSS, or puppeteer query handler like aria/, text/, xpath/, pierce/; also accepts legacy p- prefixes)",
+			description: "target element selector",
+			examples: ["aria/Sign in", "text/Continue", "xpath/...", "pierce/..."],
 		}),
-		attribute: Type.Optional(Type.String({ description: "Attribute name (get_attribute)" })),
+		attribute: Type.Optional(Type.String({ description: "attribute name", examples: ["href", "data-id"] })),
 	}),
-	{ description: "Batch arguments for get_* actions", minItems: 1 },
+	{ description: "batch get_* args", minItems: 1 },
 );
 
 const browserSchema = Type.Object({
@@ -393,56 +393,58 @@ const browserSchema = Type.Object({
 			"screenshot",
 			"close",
 		],
-		{ description: "Action to perform" },
+		{ description: "action to perform" },
 	),
-	url: Type.Optional(Type.String({ description: "URL to navigate to (goto)" })),
+	url: Type.Optional(Type.String({ description: "url to navigate to", examples: ["https://example.com"] })),
 	selector: Type.Optional(
 		Type.String({
-			description:
-				"Selector for the target element (CSS, or puppeteer query handler like aria/, text/, xpath/, pierce/; also accepts legacy p- prefixes)",
+			description: "target element selector",
+			examples: ["aria/Sign in", "text/Continue", "xpath/...", "pierce/..."],
 		}),
 	),
-	element_id: Type.Optional(Type.Number({ description: "Element ID from observe" })),
-	include_all: Type.Optional(Type.Boolean({ description: "Include non-interactive nodes in observe" })),
-	viewport_only: Type.Optional(Type.Boolean({ description: "Limit observe output to elements in the viewport" })),
+	element_id: Type.Optional(Type.Number({ description: "observed element id" })),
+	include_all: Type.Optional(Type.Boolean({ description: "include non-interactive nodes" })),
+	viewport_only: Type.Optional(Type.Boolean({ description: "limit to viewport" })),
 	args: Type.Optional(puppeteerGetArgsSchema),
-	script: Type.Optional(Type.String({ description: "JavaScript to evaluate (evaluate)" })),
-	text: Type.Optional(Type.String({ description: "Text to type (type)" })),
-	value: Type.Optional(Type.String({ description: "Value to set (fill)" })),
-	attribute: Type.Optional(Type.String({ description: "Attribute name to read (get_attribute)" })),
-	key: Type.Optional(Type.String({ description: "Keyboard key to press (press)" })),
-	timeout: Type.Optional(Type.Number({ description: "Timeout in seconds", default: 30 })),
+	script: Type.Optional(
+		Type.String({ description: "javascript expression", examples: ["document.title", "window.location.href"] }),
+	),
+	text: Type.Optional(Type.String({ description: "text to type", examples: ["hello world"] })),
+	value: Type.Optional(Type.String({ description: "value to set", examples: ["hello"] })),
+	attribute: Type.Optional(Type.String({ description: "attribute to read", examples: ["href", "data-id"] })),
+	key: Type.Optional(Type.String({ description: "keyboard key", examples: ["Enter", "Tab", "Escape"] })),
+	timeout: Type.Optional(Type.Number({ description: "timeout in seconds", default: 30 })),
 	wait_until: Type.Optional(
 		StringEnum(["load", "domcontentloaded", "networkidle0", "networkidle2"], {
-			description: "Navigation wait condition (goto)",
+			description: "navigation wait condition",
 		}),
 	),
-	full_page: Type.Optional(Type.Boolean({ description: "Capture full page screenshot (screenshot)" })),
+	full_page: Type.Optional(Type.Boolean({ description: "full page screenshot" })),
 	format: Type.Optional(
 		StringEnum(["text", "markdown"], {
-			description: "Output format for extract_readable (text/markdown)",
+			description: "output format",
 		}),
 	),
-	path: Type.Optional(Type.String({ description: "Optional path to save screenshot (relative to cwd)" })),
+	path: Type.Optional(Type.String({ description: "screenshot save path", examples: ["out.png"] })),
 	viewport: Type.Optional(
 		Type.Object({
-			width: Type.Number({ description: "Viewport width in pixels" }),
-			height: Type.Number({ description: "Viewport height in pixels" }),
-			device_scale_factor: Type.Optional(Type.Number({ description: "Device scale factor" })),
+			width: Type.Number({ description: "viewport width" }),
+			height: Type.Number({ description: "viewport height" }),
+			device_scale_factor: Type.Optional(Type.Number({ description: "device scale factor" })),
 		}),
 	),
-	delta_x: Type.Optional(Type.Number({ description: "Scroll delta X (scroll)" })),
-	delta_y: Type.Optional(Type.Number({ description: "Scroll delta Y (scroll)" })),
+	delta_x: Type.Optional(Type.Number({ description: "scroll delta x" })),
+	delta_y: Type.Optional(Type.Number({ description: "scroll delta y" })),
 	from_selector: Type.Optional(
 		Type.String({
-			description:
-				"Drag start selector (CSS, or puppeteer query handler like aria/, text/, xpath/, pierce/; also accepts legacy p- prefixes)",
+			description: "drag start selector",
+			examples: ["aria/Drag handle"],
 		}),
 	),
 	to_selector: Type.Optional(
 		Type.String({
-			description:
-				"Drag end selector (CSS, or puppeteer query handler like aria/, text/, xpath/, pierce/; also accepts legacy p- prefixes)",
+			description: "drag end selector",
+			examples: ["text/Drop zone"],
 		}),
 	),
 });

package/src/tools/calculator.ts

@@ -31,11 +31,11 @@ type Token =
 const calculatorSchema = Type.Object({
 	calculations: Type.Array(
 		Type.Object({
-			expression: Type.String({ description: "Math expression to evaluate" }),
-			prefix: Type.String({ description: "Text to prepend to the result" }),
-			suffix: Type.String({ description: "Text to append to the result" }),
+			expression: Type.String({ description: "math expression", examples: ["2 + 2", "sqrt(16)"] }),
+			prefix: Type.String({ description: "prefix text" }),
+			suffix: Type.String({ description: "suffix text" }),
 		}),
-		{ description: "List of calculations to evaluate" },
+		{ description: "calculations to evaluate" },
 	),
 });
 

package/src/tools/cancel-job.ts

@@ -6,7 +6,7 @@ import cancelJobDescription from "../prompts/tools/cancel-job.md" with { type: "
 import type { ToolSession } from "./index";
 
 const cancelJobSchema = Type.Object({
-	job_id: Type.String({ description: "Background job ID" }),
+	job_id: Type.String({ description: "background job id", examples: ["job-1234"] }),
 });
 
 type CancelJobParams = Static<typeof cancelJobSchema>;

package/src/tools/checkpoint.ts

@@ -18,13 +18,13 @@ export interface CheckpointState {
 }
 
 const checkpointSchema = Type.Object({
-	goal: Type.String({ description: "What you are investigating and why" }),
+	goal: Type.String({ description: "investigation goal", examples: ["investigate retry logic"] }),
 });
 
 type CheckpointParams = Static<typeof checkpointSchema>;
 
 const rewindSchema = Type.Object({
-	report: Type.String({ description: "Concise investigation findings to retain after rewind" }),
+	report: Type.String({ description: "investigation findings" }),
 });
 
 type RewindParams = Static<typeof rewindSchema>;

package/src/tools/debug.ts

@@ -83,51 +83,55 @@ const debugSchema = Type.Object({
 			"terminate",
 			"sessions",
 		],
-		{ description: "DAP debugger action" },
+		{ description: "dap debugger action" },
 	),
-	program: Type.Optional(Type.String({ description: "Program or script path for launch" })),
-	args: Type.Optional(Type.Array(Type.String(), { description: "Program arguments for launch" })),
-	adapter: Type.Optional(Type.String({ description: "Debugger adapter override (gdb, lldb-dap, debugpy, dlv)" })),
-	cwd: Type.Optional(Type.String({ description: "Working directory for launch or attach" })),
-	file: Type.Optional(Type.String({ description: "Source file for source breakpoints" })),
-	line: Type.Optional(Type.Number({ description: "1-indexed source line for source breakpoints" })),
-	function: Type.Optional(Type.String({ description: "Function name for function breakpoints" })),
-	name: Type.Optional(Type.String({ description: "Variable or data name for data breakpoint info" })),
-	condition: Type.Optional(Type.String({ description: "Breakpoint condition expression" })),
-	hit_condition: Type.Optional(Type.String({ description: "Breakpoint hit condition expression" })),
-	expression: Type.Optional(Type.String({ description: "Expression to evaluate in debugger context" })),
-	context: Type.Optional(Type.String({ description: "Evaluate context (watch, repl, hover, variables, clipboard)" })),
-	frame_id: Type.Optional(Type.Number({ description: "Stack frame ID for scopes/evaluate" })),
-	scope_id: Type.Optional(Type.Number({ description: "Scope variablesReference for variables requests" })),
-	variable_ref: Type.Optional(Type.Number({ description: "Variable reference for variables requests" })),
-	pid: Type.Optional(Type.Number({ description: "Process ID for attach" })),
-	port: Type.Optional(Type.Number({ description: "Port for remote attach when adapter supports it" })),
-	host: Type.Optional(Type.String({ description: "Host for remote attach when adapter supports it" })),
-	levels: Type.Optional(Type.Number({ description: "Maximum stack frames to fetch" })),
-	memory_reference: Type.Optional(Type.String({ description: "Memory reference or address" })),
-	instruction_reference: Type.Optional(
-		Type.String({ description: "Instruction address/reference for instruction breakpoints" }),
+	program: Type.Optional(Type.String({ description: "program path", examples: ["./my_app", "src/main.py"] })),
+	args: Type.Optional(Type.Array(Type.String(), { description: "program arguments", examples: [["--verbose"]] })),
+	adapter: Type.Optional(
+		Type.String({ description: "debugger adapter", examples: ["gdb", "lldb-dap", "debugpy", "dlv"] }),
 	),
-	instruction_count: Type.Optional(Type.Number({ description: "Number of instructions to disassemble" })),
-	instruction_offset: Type.Optional(Type.Number({ description: "Instruction offset for disassembly" })),
-	count: Type.Optional(Type.Number({ description: "Number of bytes to read from memory" })),
-	data: Type.Optional(Type.String({ description: "Base64-encoded memory payload for write_memory" })),
-	data_id: Type.Optional(Type.String({ description: "DAP data breakpoint identifier" })),
+	cwd: Type.Optional(Type.String({ description: "working directory", examples: ["src/"] })),
+	file: Type.Optional(Type.String({ description: "source file", examples: ["src/main.c"] })),
+	line: Type.Optional(Type.Number({ description: "source line", examples: [42] })),
+	function: Type.Optional(Type.String({ description: "function name", examples: ["main", "handle_request"] })),
+	name: Type.Optional(Type.String({ description: "variable or data name", examples: ["counter", "buffer"] })),
+	condition: Type.Optional(Type.String({ description: "breakpoint condition", examples: ["i == 10", "x > 0"] })),
+	hit_condition: Type.Optional(Type.String({ description: "hit condition" })),
+	expression: Type.Optional(Type.String({ description: "expression to evaluate", examples: ["x + 1", "obj.field"] })),
+	context: Type.Optional(
+		Type.String({ description: "evaluate context", examples: ["watch", "repl", "hover", "variables", "clipboard"] }),
+	),
+	frame_id: Type.Optional(Type.Number({ description: "stack frame id" })),
+	scope_id: Type.Optional(Type.Number({ description: "scope variables reference" })),
+	variable_ref: Type.Optional(Type.Number({ description: "variable reference" })),
+	pid: Type.Optional(Type.Number({ description: "process id for attach", examples: [12345] })),
+	port: Type.Optional(Type.Number({ description: "remote attach port", examples: [4711] })),
+	host: Type.Optional(Type.String({ description: "remote attach host", examples: ["127.0.0.1"] })),
+	levels: Type.Optional(Type.Number({ description: "max stack frames" })),
+	memory_reference: Type.Optional(
+		Type.String({ description: "memory reference or address", examples: ["0x7ffd1234"] }),
+	),
+	instruction_reference: Type.Optional(Type.String({ description: "instruction address or reference" })),
+	instruction_count: Type.Optional(Type.Number({ description: "instructions to disassemble" })),
+	instruction_offset: Type.Optional(Type.Number({ description: "instruction offset" })),
+	count: Type.Optional(Type.Number({ description: "bytes to read" })),
+	data: Type.Optional(Type.String({ description: "base64 memory payload" })),
+	data_id: Type.Optional(Type.String({ description: "data breakpoint id" })),
 	access_type: Type.Optional(
-		StringEnum(["read", "write", "readWrite"], { description: "Data breakpoint access type" }),
+		StringEnum(["read", "write", "readWrite"], { description: "data breakpoint access type" }),
 	),
-	command: Type.Optional(Type.String({ description: "Custom DAP request command" })),
+	command: Type.Optional(Type.String({ description: "custom dap request command" })),
 	arguments: Type.Optional(
 		Type.Record(Type.String(), Type.Any(), {
-			description: "Arguments object for custom_request",
+			description: "custom request arguments",
 		}),
 	),
-	offset: Type.Optional(Type.Number({ description: "Memory or instruction offset" })),
-	resolve_symbols: Type.Optional(Type.Boolean({ description: "Resolve symbols during disassembly" })),
-	allow_partial: Type.Optional(Type.Boolean({ description: "Allow partial writes for write_memory" })),
-	start_module: Type.Optional(Type.Number({ description: "Modules request start index" })),
-	module_count: Type.Optional(Type.Number({ description: "Maximum modules to fetch" })),
-	timeout: Type.Optional(Type.Number({ description: "Per-request timeout in seconds" })),
+	offset: Type.Optional(Type.Number({ description: "memory or instruction offset" })),
+	resolve_symbols: Type.Optional(Type.Boolean({ description: "resolve symbols during disassembly" })),
+	allow_partial: Type.Optional(Type.Boolean({ description: "allow partial writes" })),
+	start_module: Type.Optional(Type.Number({ description: "modules start index" })),
+	module_count: Type.Optional(Type.Number({ description: "max modules to fetch" })),
+	timeout: Type.Optional(Type.Number({ description: "per-request timeout seconds" })),
 });
 
 export type DebugParams = Static<typeof debugSchema>;

package/src/tools/exit-plan-mode.ts

@@ -8,7 +8,7 @@ import { resolvePlanPath } from "./plan-mode-guard";
 import { ToolError } from "./tool-errors";
 
 const exitPlanModeSchema = Type.Object({
-	title: Type.String({ description: "Final plan title, e.g. WP_MIGRATION_PLAN" }),
+	title: Type.String({ description: "final plan title", examples: ["WP_MIGRATION_PLAN"] }),
 });
 
 type ExitPlanModeParams = Static<typeof exitPlanModeSchema>;

package/src/tools/find.ts

@@ -30,11 +30,11 @@ import { toolResult } from "./tool-result";
 
 const findSchema = Type.Object({
 	pattern: Type.String({
-		description:
-			"Glob pattern including the search path (no separate path param), e.g. 'src/**/*.ts', 'lib/*.json'. Supports comma-separated lists like 'apps/,packages/,phases/'. Simple patterns like '*.ts' recurse from cwd.",
+		description: "glob including search path",
+		examples: ["src/**/*.ts", "lib/*.json", "apps/,packages/", "*.ts"],
 	}),
-	hidden: Type.Optional(Type.Boolean({ description: "Include hidden files and directories", default: true })),
-	limit: Type.Optional(Type.Number({ description: "Max results", default: 1000 })),
+	hidden: Type.Optional(Type.Boolean({ description: "include hidden files", default: true })),
+	limit: Type.Optional(Type.Number({ description: "max results", default: 1000 })),
 });
 
 export type FindToolInput = Static<typeof findSchema>;