@oh-my-pi/pi-coding-agent 13.1.1 → 13.2.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [13.2.0] - 2026-02-23
+### Breaking Changes
+
+- Made `description` field required in CustomTool interface
+
+## [13.1.2] - 2026-02-23
+### Breaking Changes
+
+- Removed `timeout` parameter from await tool—tool now waits indefinitely until jobs complete or the call is aborted
+- Renamed `job_ids` parameter to `jobs` in await tool schema
+- Removed `timedOut` field from await tool result details
+
 ## [13.1.1] - 2026-02-23
 
 ### Fixed

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "13.1.1",
+	"version": "13.2.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/can1357/oh-my-pi",
 	"author": "Can Boluk",
@@ -41,12 +41,12 @@
 	},
 	"dependencies": {
 		"@mozilla/readability": "^0.6",
-		"@oh-my-pi/omp-stats": "13.1.1",
-		"@oh-my-pi/pi-agent-core": "13.1.1",
-		"@oh-my-pi/pi-ai": "13.1.1",
-		"@oh-my-pi/pi-natives": "13.1.1",
-		"@oh-my-pi/pi-tui": "13.1.1",
-		"@oh-my-pi/pi-utils": "13.1.1",
+		"@oh-my-pi/omp-stats": "13.2.0",
+		"@oh-my-pi/pi-agent-core": "13.2.0",
+		"@oh-my-pi/pi-ai": "13.2.0",
+		"@oh-my-pi/pi-natives": "13.2.0",
+		"@oh-my-pi/pi-tui": "13.2.0",
+		"@oh-my-pi/pi-utils": "13.2.0",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.18",

package/src/async/job-manager.ts

@@ -47,6 +47,7 @@ export interface AsyncJobRegisterOptions {
 export class AsyncJobManager {
 	readonly #jobs = new Map<string, AsyncJob>();
 	readonly #deliveries: AsyncJobDelivery[] = [];
+	readonly #suppressedDeliveries = new Set<string>();
 	readonly #evictionTimers = new Map<string, NodeJS.Timeout>();
 	readonly #onJobComplete: AsyncJobManagerOptions["onJobComplete"];
 	readonly #maxRunningJobs: number;
@@ -81,6 +82,7 @@ export class AsyncJobManager {
 		}
 
 		const id = this.#resolveJobId(options?.id);
+		this.#suppressedDeliveries.delete(id);
 		const abortController = new AbortController();
 		const startTime = Date.now();
 
@@ -182,6 +184,23 @@ export class AsyncJobManager {
 		return this.#deliveries.length > 0;
 	}
 
+	acknowledgeDeliveries(jobIds: string[]): number {
+		const uniqueJobIds = Array.from(new Set(jobIds.map(id => id.trim()).filter(id => id.length > 0)));
+		if (uniqueJobIds.length === 0) return 0;
+
+		for (const jobId of uniqueJobIds) {
+			this.#suppressedDeliveries.add(jobId);
+		}
+
+		const before = this.#deliveries.length;
+		this.#deliveries.splice(
+			0,
+			this.#deliveries.length,
+			...this.#deliveries.filter(delivery => !this.#suppressedDeliveries.has(delivery.jobId)),
+		);
+		return before - this.#deliveries.length;
+	}
+
 	cancelAll(): void {
 		for (const job of this.getRunningJobs()) {
 			job.status = "cancelled";
@@ -234,6 +253,7 @@ export class AsyncJobManager {
 		this.#clearEvictionTimers();
 		this.#jobs.clear();
 		this.#deliveries.length = 0;
+		this.#suppressedDeliveries.clear();
 		return drained;
 	}
 
@@ -257,6 +277,7 @@ export class AsyncJobManager {
 	#scheduleEviction(jobId: string): void {
 		if (this.#retentionMs <= 0) {
 			this.#jobs.delete(jobId);
+			this.#suppressedDeliveries.delete(jobId);
 			return;
 		}
 		const existing = this.#evictionTimers.get(jobId);
@@ -266,6 +287,7 @@ export class AsyncJobManager {
 		const timer = setTimeout(() => {
 			this.#evictionTimers.delete(jobId);
 			this.#jobs.delete(jobId);
+			this.#suppressedDeliveries.delete(jobId);
 		}, this.#retentionMs);
 		timer.unref();
 		this.#evictionTimers.set(jobId, timer);
@@ -278,7 +300,14 @@ export class AsyncJobManager {
 		this.#evictionTimers.clear();
 	}
 
+	#isDeliverySuppressed(jobId: string): boolean {
+		return this.#suppressedDeliveries.has(jobId);
+	}
+
 	#enqueueDelivery(jobId: string, text: string): void {
+		if (this.#isDeliverySuppressed(jobId)) {
+			return;
+		}
 		this.#deliveries.push({
 			jobId,
 			text,
@@ -308,10 +337,21 @@ export class AsyncJobManager {
 	async #runDeliveryLoop(): Promise<void> {
 		while (this.#deliveries.length > 0) {
 			const delivery = this.#deliveries[0];
+			if (this.#isDeliverySuppressed(delivery.jobId)) {
+				this.#deliveries.shift();
+				continue;
+			}
 			const waitMs = delivery.nextAttemptAt - Date.now();
 			if (waitMs > 0) {
 				await Bun.sleep(waitMs);
 			}
+			if (this.#deliveries[0] !== delivery) {
+				continue;
+			}
+			if (this.#isDeliverySuppressed(delivery.jobId)) {
+				this.#deliveries.shift();
+				continue;
+			}
 
 			try {
 				await this.#onJobComplete(delivery.jobId, delivery.text, this.#jobs.get(delivery.jobId));
@@ -321,7 +361,9 @@ export class AsyncJobManager {
 				delivery.lastError = error instanceof Error ? error.message : String(error);
 				delivery.nextAttemptAt = Date.now() + this.#getRetryDelay(delivery.attempt);
 				this.#deliveries.shift();
-				this.#deliveries.push(delivery);
+				if (!this.#isDeliverySuppressed(delivery.jobId)) {
+					this.#deliveries.push(delivery);
+				}
 				logger.warn("Async job completion delivery failed", {
 					jobId: delivery.jobId,
 					attempt: delivery.attempt,

package/src/capability/tool.ts

@@ -15,7 +15,7 @@ export interface CustomTool {
 	/** Absolute path to tool definition file */
 	path: string;
 	/** Tool description */
-	description?: string;
+	description: string;
 	/** Tool implementation (script path or inline) */
 	implementation?: string;
 	/** Source level */

package/src/config/settings-schema.ts

@@ -176,6 +176,16 @@ export const SETTINGS_SCHEMA = {
 			description: "Use blue instead of green for diff additions",
 		},
 	},
+	"display.tabWidth": {
+		type: "number",
+		default: 3,
+		ui: {
+			tab: "display",
+			label: "Tab width",
+			description: "Default number of spaces used when rendering tab characters",
+			submenu: true,
+		},
+	},
 	defaultThinkingLevel: {
 		type: "enum",
 		values: ["off", "minimal", "low", "medium", "high", "xhigh"] as const,

package/src/config/settings.ts

@@ -13,7 +13,7 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { isEnoent, logger, procmgr } from "@oh-my-pi/pi-utils";
+import { isEnoent, logger, procmgr, setDefaultTabWidth } from "@oh-my-pi/pi-utils";
 import { getAgentDbPath, getAgentDir, getProjectDir } from "@oh-my-pi/pi-utils/dirs";
 import { YAML } from "bun";
 import { type Settings as SettingsCapabilityItem, settingsCapability } from "../capability/settings";
@@ -438,6 +438,7 @@ export class Settings {
 
 		// Build merged view
 		this.#rebuildMerged();
+		this.#fireAllHooks();
 		return this;
 	}
 
@@ -610,6 +611,16 @@ export class Settings {
 		this.#merged = this.#deepMerge(this.#merged, this.#overrides);
 	}
 
+	#fireAllHooks(): void {
+		for (const key of Object.keys(SETTING_HOOKS) as SettingPath[]) {
+			const hook = SETTING_HOOKS[key];
+			if (hook) {
+				const value = this.get(key);
+				hook(value, value);
+			}
+		}
+	}
+
 	#deepMerge(base: RawSettings, overrides: RawSettings): RawSettings {
 		const result = { ...base };
 		for (const key of Object.keys(overrides)) {
@@ -666,6 +677,11 @@ const SETTING_HOOKS: Partial<Record<SettingPath, SettingHook<any>>> = {
 			});
 		}
 	},
+	"display.tabWidth": value => {
+		if (typeof value === "number") {
+			setDefaultTabWidth(value);
+		}
+	},
 };
 
 // ═══════════════════════════════════════════════════════════════════════════

package/src/discovery/builtin.ts

@@ -656,20 +656,30 @@ async function loadTools(ctx: LoadContext): Promise<LoadResult<CustomTool>> {
 				transform: (name, content, path, source) => {
 					if (name.endsWith(".json")) {
 						const data = parseJSON<{ name?: string; description?: string }>(content);
+						const toolName = data?.name || name.replace(/\.json$/, "");
+						const description =
+							typeof data?.description === "string" && data.description.trim()
+								? data.description
+								: `${toolName} custom tool`;
 						return {
-							name: data?.name || name.replace(/\.json$/, ""),
+							name: toolName,
 							path,
-							description: data?.description,
+							description,
 							level,
 							_source: source,
 						};
 					}
 					if (name.endsWith(".md")) {
 						const { frontmatter } = parseFrontmatter(content, { source: path });
+						const toolName = (frontmatter.name as string) || name.replace(/\.md$/, "");
+						const description =
+							typeof frontmatter.description === "string" && frontmatter.description.trim()
+								? String(frontmatter.description)
+								: `${toolName} custom tool`;
 						return {
-							name: (frontmatter.name as string) || name.replace(/\.md$/, ""),
+							name: toolName,
 							path,
-							description: frontmatter.description as string | undefined,
+							description,
 							level,
 							_source: source,
 						};
@@ -679,6 +689,7 @@ async function loadTools(ctx: LoadContext): Promise<LoadResult<CustomTool>> {
 					return {
 						name: toolName,
 						path,
+						description: `${toolName} custom tool`,
 						level,
 						_source: source,
 					};
@@ -715,7 +726,7 @@ async function loadTools(ctx: LoadContext): Promise<LoadResult<CustomTool>> {
 			items.push({
 				name: entryName,
 				path: indexPath,
-				description: undefined,
+				description: `${entryName} custom tool`,
 				level,
 				_source: createSourceMeta(PROVIDER_ID, indexPath, level),
 			});

package/src/discovery/claude-plugins.ts

@@ -152,6 +152,7 @@ async function loadTools(ctx: LoadContext): Promise<LoadResult<CustomTool>> {
 					return {
 						name: toolName,
 						path: filePath,
+						description: `${toolName} custom tool`,
 						level: root.scope,
 						_source: source,
 					};

package/src/discovery/claude.ts

@@ -324,10 +324,10 @@ async function loadTools(ctx: LoadContext): Promise<LoadResult<CustomTool>> {
 	const userResult = await loadFilesFromDir<CustomTool>(ctx, userToolsDir, PROVIDER_ID, "user", {
 		transform: (name, _content, path, source) => {
 			const toolName = name.replace(/\.(ts|js|sh|bash|py)$/, "");
-
 			return {
 				name: toolName,
 				path,
+				description: `${toolName} custom tool`,
 				level: "user",
 				_source: source,
 			};
@@ -343,10 +343,10 @@ async function loadTools(ctx: LoadContext): Promise<LoadResult<CustomTool>> {
 	const projectResult = await loadFilesFromDir<CustomTool>(ctx, projectToolsDir, PROVIDER_ID, "project", {
 		transform: (name, _content, path, source) => {
 			const toolName = name.replace(/\.(ts|js|sh|bash|py)$/, "");
-
 			return {
 				name: toolName,
 				path,
+				description: `${toolName} custom tool`,
 				level: "project",
 				_source: source,
 			};

package/src/modes/components/diff.ts

@@ -1,3 +1,4 @@
+import { getIndentation } from "@oh-my-pi/pi-utils";
 import * as Diff from "diff";
 import { theme } from "../../modes/theme/theme";
 import { replaceTabs } from "../../tools/render-utils";
@@ -12,26 +13,30 @@ const DIM_OFF = "\x1b[22m";
  * before the first non-whitespace character; remaining tabs in code
  * content are replaced with spaces (like replaceTabs).
  */
-function visualizeIndent(text: string): string {
+function visualizeIndent(text: string, filePath?: string): string {
 	const match = text.match(/^([ \t]+)/);
-	if (!match) return replaceTabs(text);
+	if (!match) return replaceTabs(text, filePath);
 	const indent = match[1];
 	const rest = text.slice(indent.length);
-	// Normalize: collapse 3-space groups (tab-width) into tab arrows,
-	// then handle remaining tabs and lone spaces.
-	const normalized = indent.replaceAll("\t", "   ");
+	const indentation = getIndentation(filePath);
+	const tabWidth = indentation.length;
+	const leftPadding = Math.floor(tabWidth / 2);
+	const rightPadding = Math.max(0, tabWidth - leftPadding - 1);
+	const tabMarker = `${DIM}${" ".repeat(leftPadding)}→${" ".repeat(rightPadding)}${DIM_OFF}`;
+	// Normalize: collapse configured tab-width groups into tab markers, then handle remaining spaces.
+	const normalized = indent.replaceAll("\t", indentation);
 	let visible = "";
 	let pos = 0;
 	while (pos < normalized.length) {
-		if (pos + 3 <= normalized.length && normalized.slice(pos, pos + 3) === "   ") {
-			visible += `${DIM} → ${DIM_OFF}`;
-			pos += 3;
+		if (pos + tabWidth <= normalized.length && normalized.slice(pos, pos + tabWidth) === indentation) {
+			visible += tabMarker;
+			pos += tabWidth;
 		} else {
 			visible += `${DIM}·${DIM_OFF}`;
 			pos++;
 		}
 	}
-	return `${visible}${replaceTabs(rest)}`;
+	return `${visible}${replaceTabs(rest, filePath)}`;
 }
 
 /**
@@ -96,7 +101,7 @@ function renderIntraLineDiff(oldContent: string, newContent: string): { removedL
 }
 
 export interface RenderDiffOptions {
-	/** File path (unused, kept for API compatibility) */
+	/** File path used to resolve indentation (.editorconfig + defaults) */
 	filePath?: string;
 }
 
@@ -106,7 +111,7 @@ export interface RenderDiffOptions {
  * - Removed lines: red, with inverse on changed tokens
  * - Added lines: green, with inverse on changed tokens
  */
-export function renderDiff(diffText: string, _options: RenderDiffOptions = {}): string {
+export function renderDiff(diffText: string, options: RenderDiffOptions = {}): string {
 	const lines = diffText.split("\n");
 	const result: string[] = [];
 
@@ -154,30 +159,55 @@ export function renderDiff(diffText: string, _options: RenderDiffOptions = {}):
 				const added = addedLines[0];
 
 				const { removedLine, addedLine } = renderIntraLineDiff(
-					replaceTabs(removed.content),
-					replaceTabs(added.content),
+					replaceTabs(removed.content, options.filePath),
+					replaceTabs(added.content, options.filePath),
 				);
 
-				result.push(theme.fg("toolDiffRemoved", formatLine("-", removed.lineNum, visualizeIndent(removedLine))));
-				result.push(theme.fg("toolDiffAdded", formatLine("+", added.lineNum, visualizeIndent(addedLine))));
+				result.push(
+					theme.fg(
+						"toolDiffRemoved",
+						formatLine("-", removed.lineNum, visualizeIndent(removedLine, options.filePath)),
+					),
+				);
+				result.push(
+					theme.fg("toolDiffAdded", formatLine("+", added.lineNum, visualizeIndent(addedLine, options.filePath))),
+				);
 			} else {
 				// Show all removed lines first, then all added lines
 				for (const removed of removedLines) {
 					result.push(
-						theme.fg("toolDiffRemoved", formatLine("-", removed.lineNum, visualizeIndent(removed.content))),
+						theme.fg(
+							"toolDiffRemoved",
+							formatLine("-", removed.lineNum, visualizeIndent(removed.content, options.filePath)),
+						),
 					);
 				}
 				for (const added of addedLines) {
-					result.push(theme.fg("toolDiffAdded", formatLine("+", added.lineNum, visualizeIndent(added.content))));
+					result.push(
+						theme.fg(
+							"toolDiffAdded",
+							formatLine("+", added.lineNum, visualizeIndent(added.content, options.filePath)),
+						),
+					);
 				}
 			}
 		} else if (parsed.prefix === "+") {
 			// Standalone added line
-			result.push(theme.fg("toolDiffAdded", formatLine("+", parsed.lineNum, visualizeIndent(parsed.content))));
+			result.push(
+				theme.fg(
+					"toolDiffAdded",
+					formatLine("+", parsed.lineNum, visualizeIndent(parsed.content, options.filePath)),
+				),
+			);
 			i++;
 		} else {
 			// Context line
-			result.push(theme.fg("toolDiffContext", formatLine(" ", parsed.lineNum, visualizeIndent(parsed.content))));
+			result.push(
+				theme.fg(
+					"toolDiffContext",
+					formatLine(" ", parsed.lineNum, visualizeIndent(parsed.content, options.filePath)),
+				),
+			);
 			i++;
 		}
 	}

package/src/prompts/system/custom-system-prompt.md

@@ -16,6 +16,16 @@
 </file>
 {{/list}}
 </instructions>
+{{/if}}
+{{#if git.isRepo}}
+## Version Control
+Snapshot; does not update during conversation.
+Current branch: {{git.currentBranch}}
+Main branch: {{git.mainBranch}}
+{{git.status}}
+### History
+{{git.commits}}
+{{/if}}
 </project>
 {{/ifAny}}
 {{#if skills.length}}

package/src/tools/await-tool.ts

@@ -5,16 +5,11 @@ import awaitDescription from "../prompts/tools/await.md" with { type: "text" };
 import type { ToolSession } from "./index";
 
 const awaitSchema = Type.Object({
-	job_ids: Type.Optional(
+	jobs: Type.Optional(
 		Type.Array(Type.String(), {
 			description: "Specific job IDs to wait for. If omitted, waits for any running job.",
 		}),
 	),
-	timeout: Type.Optional(
-		Type.Number({
-			description: "Maximum seconds to wait before returning (default: 300)",
-		}),
-	),
 });
 
 type AwaitParams = Static<typeof awaitSchema>;
@@ -31,7 +26,6 @@ interface AwaitResult {
 
 export interface AwaitToolDetails {
 	jobs: AwaitResult[];
-	timedOut: boolean;
 }
 
 export class AwaitTool implements AgentTool<typeof awaitSchema, AwaitToolDetails> {
@@ -61,12 +55,11 @@ export class AwaitTool implements AgentTool<typeof awaitSchema, AwaitToolDetails
 		if (!manager) {
 			return {
 				content: [{ type: "text", text: "Async execution is disabled; no background jobs to poll." }],
-				details: { jobs: [], timedOut: false },
+				details: { jobs: [] },
 			};
 		}
 
-		const timeoutMs = (params.timeout ?? 300) * 1000;
-		const requestedIds = params.job_ids;
+		const requestedIds = params.jobs;
 
 		// Resolve which jobs to watch
 		const jobsToWatch = requestedIds?.length
@@ -79,19 +72,18 @@ export class AwaitTool implements AgentTool<typeof awaitSchema, AwaitToolDetails
 				: "No running background jobs to wait for.";
 			return {
 				content: [{ type: "text", text: message }],
-				details: { jobs: [], timedOut: false },
+				details: { jobs: [] },
 			};
 		}
 
 		// If all watched jobs are already done, return immediately
 		const runningJobs = jobsToWatch.filter(j => j.status === "running");
 		if (runningJobs.length === 0) {
-			return this.#buildResult(jobsToWatch, false);
+			return this.#buildResult(manager, jobsToWatch);
 		}
 
-		// Block until at least one running job finishes or timeout
+		// Block until at least one running job finishes or the call is aborted
 		const racePromises: Promise<unknown>[] = runningJobs.map(j => j.promise);
-		racePromises.push(Bun.sleep(timeoutMs));
 
 		if (signal) {
 			const { promise: abortPromise, resolve: abortResolve } = Promise.withResolvers<void>();
@@ -108,17 +100,14 @@ export class AwaitTool implements AgentTool<typeof awaitSchema, AwaitToolDetails
 		}
 
 		if (signal?.aborted) {
-			return this.#buildResult(jobsToWatch, false);
+			return this.#buildResult(manager, jobsToWatch);
 		}
 
-		// Check if we timed out (all watched jobs still running)
-		const stillRunning = jobsToWatch.filter(j => j.status === "running");
-		const timedOut = stillRunning.length === runningJobs.length;
-
-		return this.#buildResult(jobsToWatch, timedOut);
+		return this.#buildResult(manager, jobsToWatch);
 	}
 
 	#buildResult(
+		manager: NonNullable<ToolSession["asyncJobManager"]>,
 		jobs: {
 			id: string;
 			type: "bash" | "task";
@@ -128,7 +117,6 @@ export class AwaitTool implements AgentTool<typeof awaitSchema, AwaitToolDetails
 			resultText?: string;
 			errorText?: string;
 		}[],
-		timedOut: boolean,
 	): AgentToolResult<AwaitToolDetails> {
 		const now = Date.now();
 		const jobResults: AwaitResult[] = jobs.map(j => ({
@@ -141,14 +129,12 @@ export class AwaitTool implements AgentTool<typeof awaitSchema, AwaitToolDetails
 			...(j.errorText ? { errorText: j.errorText } : {}),
 		}));
 
+		manager.acknowledgeDeliveries(jobResults.filter(j => j.status !== "running").map(j => j.id));
+
 		const completed = jobResults.filter(j => j.status !== "running");
 		const running = jobResults.filter(j => j.status === "running");
 
 		const lines: string[] = [];
-		if (timedOut) {
-			lines.push("Timed out waiting for jobs to complete.\n");
-		}
-
 		if (completed.length > 0) {
 			lines.push(`## Completed (${completed.length})\n`);
 			for (const j of completed) {
@@ -173,7 +159,7 @@ export class AwaitTool implements AgentTool<typeof awaitSchema, AwaitToolDetails
 
 		return {
 			content: [{ type: "text", text: lines.join("\n") }],
-			details: { jobs: jobResults, timedOut },
+			details: { jobs: jobResults },
 		};
 	}
 }

package/src/tools/render-utils.ts

@@ -6,11 +6,14 @@
  */
 import * as os from "node:os";
 import { type Ellipsis, truncateToWidth } from "@oh-my-pi/pi-tui";
-import { pluralize } from "@oh-my-pi/pi-utils";
+import { getIndentation, pluralize } from "@oh-my-pi/pi-utils";
 import type { Theme } from "../modes/theme/theme";
 
-export { Ellipsis, replaceTabs, truncateToWidth } from "@oh-my-pi/pi-tui";
+export { Ellipsis, truncateToWidth } from "@oh-my-pi/pi-tui";
 
+export function replaceTabs(text: string, file?: string): string {
+	return text.replaceAll("\t", getIndentation(file));
+}
 // =============================================================================
 // Standardized Display Constants
 // =============================================================================

package/src/tools/todo-write.ts

@@ -41,16 +41,18 @@ export interface TodoWriteToolDetails {
 // Schema
 // =============================================================================
 
-const StatusEnum = StringEnum(["pending", "in_progress", "completed", "abandoned"] as const);
+const StatusEnum = StringEnum(["pending", "in_progress", "completed", "abandoned"] as const, {
+	description: "Task status",
+});
 
 const InputTask = Type.Object({
-	content: Type.String(),
+	content: Type.String({ description: "Task description" }),
 	status: Type.Optional(StatusEnum),
-	notes: Type.Optional(Type.String()),
+	notes: Type.Optional(Type.String({ description: "Additional context or notes" })),
 });
 
 const InputPhase = Type.Object({
-	name: Type.String(),
+	name: Type.String({ description: "Phase name" }),
 	tasks: Type.Optional(Type.Array(InputTask)),
 });
 
@@ -63,21 +65,21 @@ const todoWriteSchema = Type.Object({
 			}),
 			Type.Object({
 				op: Type.Literal("add_phase"),
-				name: Type.String(),
+				name: Type.String({ description: "Phase name" }),
 				tasks: Type.Optional(Type.Array(InputTask)),
 			}),
 			Type.Object({
 				op: Type.Literal("add_task"),
 				phase: Type.String({ description: "Phase ID, e.g. phase-1" }),
-				content: Type.String(),
-				notes: Type.Optional(Type.String()),
+				content: Type.String({ description: "Task description" }),
+				notes: Type.Optional(Type.String({ description: "Additional context or notes" })),
 			}),
 			Type.Object({
 				op: Type.Literal("update"),
 				id: Type.String({ description: "Task ID, e.g. task-3" }),
 				status: Type.Optional(StatusEnum),
-				content: Type.Optional(Type.String()),
-				notes: Type.Optional(Type.String()),
+				content: Type.Optional(Type.String({ description: "Updated task description" })),
+				notes: Type.Optional(Type.String({ description: "Additional context or notes" })),
 			}),
 			Type.Object({
 				op: Type.Literal("remove_task"),