@oh-my-pi/pi-coding-agent 3.24.0 → 3.25.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## [Unreleased]
 
+## [3.25.0] - 2026-01-07
+### Added
+
+- Added `complete` tool for structured subagent output with JSON schema validation
+- Added `query` parameter to output tool for jq-like JSON querying
+- Added `output_schema` parameter to task tool for structured subagent completion
+- Added JTD (JSON Type Definition) to JSON Schema converter for schema flexibility
+- Added memorable two-word task identifiers (e.g., SwiftFalcon) for better task tracking
+
+### Changed
+
+- Changed task output IDs from `agent_index` format to memorable names for easier reference
+- Changed subagent completion flow to require explicit `complete` tool call with retry reminders
+- Simplified worker agent system prompt to be more concise and focused
+
 ## [3.24.0] - 2026-01-07
 ### Added
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "3.24.0",
+	"version": "3.25.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"ompConfig": {
@@ -40,9 +40,9 @@
 	},
 	"dependencies": {
 		"@mariozechner/pi-ai": "^0.37.4",
-		"@oh-my-pi/pi-agent-core": "3.24.0",
-		"@oh-my-pi/pi-git-tool": "3.24.0",
-		"@oh-my-pi/pi-tui": "3.24.0",
+		"@oh-my-pi/pi-agent-core": "3.25.0",
+		"@oh-my-pi/pi-git-tool": "3.25.0",
+		"@oh-my-pi/pi-tui": "3.25.0",
 		"@openai/agents": "^0.3.7",
 		"@sinclair/typebox": "^0.34.46",
 		"ajv": "^8.17.1",

package/src/core/custom-commands/bundled/wt/index.ts

@@ -9,6 +9,7 @@ import { formatStats, getStats } from "../../../../lib/worktree/stats";
 import type { HookCommandContext } from "../../../hooks/types";
 import { discoverAgents, getAgent } from "../../../tools/task/discovery";
 import { runSubprocess } from "../../../tools/task/executor";
+import { generateTaskName } from "../../../tools/task/name-generator";
 import type { AgentDefinition } from "../../../tools/task/types";
 import type { CustomCommand, CustomCommandAPI } from "../../types";
 
@@ -265,6 +266,7 @@ async function handleSpawn(args: SpawnArgs, ctx: HookCommandContext): Promise<st
 		agent,
 		task: args.task,
 		index: 0,
+		taskId: generateTaskName(),
 		context,
 	});
 
@@ -322,6 +324,7 @@ async function handleParallel(args: ParallelTask[], ctx: HookCommandContext): Pr
 			agent,
 			task: task.task,
 			index,
+			taskId: generateTaskName(),
 			context: `Scope: ${task.scope}`,
 		});
 		await updateSession(session.id, {

package/src/core/sdk.ts

@@ -149,6 +149,11 @@ export interface CreateAgentSessionOptions {
 	/** Tool names explicitly requested (enables disabled-by-default tools) */
 	toolNames?: string[];
 
+	/** Output schema for structured completion (subagents) */
+	outputSchema?: unknown;
+	/** Whether to include the complete tool by default */
+	requireCompleteTool?: boolean;
+
 	/** Session manager. Default: SessionManager.create(cwd) */
 	sessionManager?: SessionManager;
 
@@ -608,6 +613,8 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		hasUI: options.hasUI ?? false,
 		rulebookRules,
 		eventBus,
+		outputSchema: options.outputSchema,
+		requireCompleteTool: options.requireCompleteTool,
 		getSessionFile: () => sessionManager.getSessionFile() ?? null,
 		getSessionSpawns: () => options.spawns ?? "*",
 		settings: settingsManager,

package/src/core/tools/complete.ts

@@ -0,0 +1,131 @@
+/**
+ * Complete tool for structured subagent output.
+ *
+ * Subagents must call this tool to finish and return structured JSON output.
+ */
+
+import type { AgentTool } from "@oh-my-pi/pi-agent-core";
+import { Type } from "@sinclair/typebox";
+import Ajv, { type ErrorObject, type ValidateFunction } from "ajv";
+import type { ToolSession } from "./index";
+import { jtdToJsonSchema } from "./jtd-to-json-schema";
+import { subprocessToolRegistry } from "./task/subprocess-tool-registry";
+
+export interface CompleteDetails {
+	data: unknown;
+	status: "success" | "aborted";
+	error?: string;
+}
+
+const ajv = new Ajv({ allErrors: true, strict: false });
+
+function normalizeSchema(schema: unknown): { normalized?: unknown; error?: string } {
+	if (schema === undefined || schema === null) return {};
+	if (typeof schema === "string") {
+		try {
+			return { normalized: JSON.parse(schema) };
+		} catch (err) {
+			return { error: err instanceof Error ? err.message : String(err) };
+		}
+	}
+	return { normalized: schema };
+}
+
+function formatSchema(schema: unknown): string {
+	if (schema === undefined) return "No schema provided.";
+	if (typeof schema === "string") return schema;
+	try {
+		return JSON.stringify(schema, null, 2);
+	} catch {
+		return "[unserializable schema]";
+	}
+}
+
+function formatAjvErrors(errors: ErrorObject[] | null | undefined): string {
+	if (!errors || errors.length === 0) return "Unknown schema validation error.";
+	return errors
+		.map((err) => {
+			const path = err.instancePath ? `${err.instancePath}: ` : "";
+			return `${path}${err.message ?? "invalid"}`;
+		})
+		.join("; ");
+}
+
+export function createCompleteTool(session: ToolSession) {
+	const schemaResult = normalizeSchema(session.outputSchema);
+	// Convert JTD to JSON Schema if needed (auto-detected)
+	const normalizedSchema =
+		schemaResult.normalized !== undefined ? jtdToJsonSchema(schemaResult.normalized) : undefined;
+	let validate: ValidateFunction | undefined;
+	let schemaError = schemaResult.error;
+
+	if (normalizedSchema !== undefined && !schemaError) {
+		try {
+			validate = ajv.compile(normalizedSchema as any);
+		} catch (err) {
+			schemaError = err instanceof Error ? err.message : String(err);
+		}
+	}
+
+	const schemaHint = formatSchema(normalizedSchema ?? session.outputSchema);
+
+	// Use actual schema if provided, otherwise fall back to Type.Any
+	// Merge description into the JSON schema for better tool documentation
+	const dataSchema = normalizedSchema
+		? Type.Unsafe({
+				...(normalizedSchema as object),
+				description: "Structured output matching the schema:\n" + schemaHint,
+			})
+		: Type.Any({ description: "Structured JSON output (no schema specified)" });
+
+	const completeParams = Type.Object({
+		data: dataSchema,
+		status: Type.Optional(
+			Type.Union([Type.Literal("success"), Type.Literal("aborted")], {
+				default: "success",
+				description: "Use 'aborted' if the task cannot be completed",
+			}),
+		),
+		error: Type.Optional(Type.String({ description: "Error message when status is 'aborted'" })),
+	});
+
+	const tool: AgentTool<typeof completeParams, CompleteDetails> = {
+		name: "complete",
+		label: "Complete",
+		description:
+			"Finish the task with structured JSON output. Call exactly once at the end of the task.\n\n" +
+			"If you cannot complete the task, call with status='aborted' and an error message.",
+		parameters: completeParams,
+		execute: async (_toolCallId, params) => {
+			const status = params.status ?? "success";
+
+			// Skip schema validation when aborting - the agent is giving up
+			if (status === "success") {
+				if (schemaError) {
+					throw new Error(`Invalid output schema: ${schemaError}`);
+				}
+				if (validate && !validate(params.data)) {
+					throw new Error(`Output does not match schema: ${formatAjvErrors(validate.errors)}`);
+				}
+			}
+
+			const responseText =
+				status === "aborted"
+					? `Task aborted: ${params.error || "No reason provided"}`
+					: "Completion recorded.";
+
+			return {
+				content: [{ type: "text", text: responseText }],
+				details: { data: params.data, status, error: params.error },
+			};
+		},
+	};
+
+	return tool;
+}
+
+// Register subprocess tool handler for extraction + termination.
+subprocessToolRegistry.register<CompleteDetails>("complete", {
+	extractData: (event) => event.result?.details as CompleteDetails | undefined,
+	shouldTerminate: () => true,
+});

package/src/core/tools/index.test.ts

@@ -50,6 +50,14 @@ describe("createTools", () => {
 		expect(names).toEqual(["report_finding"]);
 	});
 
+	it("includes complete tool when required", async () => {
+		const session = createTestSession({ requireCompleteTool: true });
+		const tools = await createTools(session);
+		const names = tools.map((t) => t.name);
+
+		expect(names).toContain("complete");
+	});
+
 	it("excludes ask tool when hasUI is false", async () => {
 		const session = createTestSession({ hasUI: false });
 		const tools = await createTools(session);
@@ -175,6 +183,6 @@ describe("createTools", () => {
 	});
 
 	it("HIDDEN_TOOLS contains review tools", () => {
-		expect(Object.keys(HIDDEN_TOOLS).sort()).toEqual(["report_finding", "submit_review"]);
+		expect(Object.keys(HIDDEN_TOOLS).sort()).toEqual(["complete", "report_finding", "submit_review"]);
 	});
 });

package/src/core/tools/index.ts

@@ -1,5 +1,6 @@
 export { type AskToolDetails, askTool, createAskTool } from "./ask";
 export { type BashToolDetails, createBashTool } from "./bash";
+export { createCompleteTool } from "./complete";
 export { createEditTool } from "./edit";
 // Exa MCP tools (22 tools)
 export { exaTools } from "./exa/index";
@@ -54,6 +55,7 @@ import type { Rule } from "../../capability/rule";
 import type { EventBus } from "../event-bus";
 import { createAskTool } from "./ask";
 import { createBashTool } from "./bash";
+import { createCompleteTool } from "./complete";
 import { createEditTool } from "./edit";
 import { createFindTool } from "./find";
 import { createGitTool } from "./git";
@@ -83,6 +85,10 @@ export interface ToolSession {
 	rulebookRules: Rule[];
 	/** Event bus for tool/extension communication */
 	eventBus?: EventBus;
+	/** Output schema for structured completion (subagents) */
+	outputSchema?: unknown;
+	/** Whether to include the complete tool by default */
+	requireCompleteTool?: boolean;
 	/** Get session file */
 	getSessionFile: () => string | null;
 	/** Get session spawns */
@@ -121,6 +127,7 @@ export const BUILTIN_TOOLS: Record<string, ToolFactory> = {
 };
 
 export const HIDDEN_TOOLS: Record<string, ToolFactory> = {
+	complete: createCompleteTool,
 	report_finding: () => reportFindingTool,
 	submit_review: () => submitReviewTool,
 };
@@ -131,13 +138,19 @@ export type ToolName = keyof typeof BUILTIN_TOOLS;
  * Create tools from BUILTIN_TOOLS registry.
  */
 export async function createTools(session: ToolSession, toolNames?: string[]): Promise<Tool[]> {
-	const requestedTools = toolNames && toolNames.length > 0 ? toolNames : undefined;
+	const includeComplete = session.requireCompleteTool === true;
+	const requestedTools = toolNames && toolNames.length > 0 ? [...new Set(toolNames)] : undefined;
 	const allTools: Record<string, ToolFactory> = { ...BUILTIN_TOOLS, ...HIDDEN_TOOLS };
+	if (includeComplete && requestedTools && !requestedTools.includes("complete")) {
+		requestedTools.push("complete");
+	}
+
 	const entries = requestedTools
-		? requestedTools
-				.filter((name, index) => requestedTools.indexOf(name) === index && name in allTools)
-				.map((name) => [name, allTools[name]] as const)
-		: Object.entries(BUILTIN_TOOLS);
+		? requestedTools.filter((name) => name in allTools).map((name) => [name, allTools[name]] as const)
+		: [
+				...Object.entries(BUILTIN_TOOLS),
+				...(includeComplete ? ([["complete", HIDDEN_TOOLS.complete]] as const) : []),
+			];
 	const results = await Promise.all(entries.map(([, factory]) => factory(session)));
 	const tools = results.filter((t): t is Tool => t !== null);
 

package/src/core/tools/jtd-to-json-schema.ts

@@ -0,0 +1,274 @@
+/**
+ * Convert JSON Type Definition (JTD) to JSON Schema.
+ *
+ * JTD (RFC 8927) is a simpler schema format. This converter allows users to
+ * write schemas in JTD and have them converted to JSON Schema for model APIs.
+ *
+ * @see https://jsontypedef.com/
+ * @see https://datatracker.ietf.org/doc/html/rfc8927
+ */
+
+type JTDPrimitive =
+   | "boolean"
+   | "string"
+   | "timestamp"
+   | "float32"
+   | "float64"
+   | "int8"
+   | "uint8"
+   | "int16"
+   | "uint16"
+   | "int32"
+   | "uint32";
+
+interface JTDType {
+   type: JTDPrimitive;
+}
+
+interface JTDEnum {
+   enum: string[];
+}
+
+interface JTDElements {
+   elements: JTDSchema;
+}
+
+interface JTDValues {
+   values: JTDSchema;
+}
+
+interface JTDProperties {
+   properties?: Record<string, JTDSchema>;
+   optionalProperties?: Record<string, JTDSchema>;
+}
+
+interface JTDDiscriminator {
+   discriminator: string;
+   mapping: Record<string, JTDProperties>;
+}
+
+interface JTDRef {
+   ref: string;
+}
+
+interface JTDEmpty {}
+
+type JTDSchema =
+   | JTDType
+   | JTDEnum
+   | JTDElements
+   | JTDValues
+   | JTDProperties
+   | JTDDiscriminator
+   | JTDRef
+   | JTDEmpty;
+
+const primitiveMap: Record<JTDPrimitive, string> = {
+   boolean: "boolean",
+   string: "string",
+   timestamp: "string", // ISO 8601
+   float32: "number",
+   float64: "number",
+   int8: "integer",
+   uint8: "integer",
+   int16: "integer",
+   uint16: "integer",
+   int32: "integer",
+   uint32: "integer",
+};
+
+function isJTDType(schema: unknown): schema is JTDType {
+   return typeof schema === "object" && schema !== null && "type" in schema;
+}
+
+function isJTDEnum(schema: unknown): schema is JTDEnum {
+   return typeof schema === "object" && schema !== null && "enum" in schema;
+}
+
+function isJTDElements(schema: unknown): schema is JTDElements {
+   return typeof schema === "object" && schema !== null && "elements" in schema;
+}
+
+function isJTDValues(schema: unknown): schema is JTDValues {
+   return typeof schema === "object" && schema !== null && "values" in schema;
+}
+
+function isJTDProperties(schema: unknown): schema is JTDProperties {
+   return (
+      typeof schema === "object" &&
+      schema !== null &&
+      ("properties" in schema || "optionalProperties" in schema)
+   );
+}
+
+function isJTDDiscriminator(schema: unknown): schema is JTDDiscriminator {
+   return typeof schema === "object" && schema !== null && "discriminator" in schema;
+}
+
+function isJTDRef(schema: unknown): schema is JTDRef {
+   return typeof schema === "object" && schema !== null && "ref" in schema;
+}
+
+function convertSchema(schema: unknown): unknown {
+   if (schema === null || typeof schema !== "object") {
+      return {};
+   }
+
+   // Type form: { type: "string" } → { type: "string" }
+   if (isJTDType(schema)) {
+      const jsonType = primitiveMap[schema.type as JTDPrimitive];
+      if (!jsonType) {
+         return { type: schema.type };
+      }
+      const result: Record<string, unknown> = { type: jsonType };
+      // Add format for timestamp
+      if (schema.type === "timestamp") {
+         result.format = "date-time";
+      }
+      return result;
+   }
+
+   // Enum form: { enum: ["a", "b"] } → { enum: ["a", "b"] }
+   if (isJTDEnum(schema)) {
+      return { enum: schema.enum };
+   }
+
+   // Elements form: { elements: { type: "string" } } → { type: "array", items: ... }
+   if (isJTDElements(schema)) {
+      return {
+         type: "array",
+         items: convertSchema(schema.elements),
+      };
+   }
+
+   // Values form: { values: { type: "string" } } → { type: "object", additionalProperties: ... }
+   if (isJTDValues(schema)) {
+      return {
+         type: "object",
+         additionalProperties: convertSchema(schema.values),
+      };
+   }
+
+   // Properties form: { properties: {...}, optionalProperties: {...} }
+   if (isJTDProperties(schema)) {
+      const properties: Record<string, unknown> = {};
+      const required: string[] = [];
+
+      // Required properties
+      if (schema.properties) {
+         for (const [key, value] of Object.entries(schema.properties)) {
+            properties[key] = convertSchema(value);
+            required.push(key);
+         }
+      }
+
+      // Optional properties
+      if (schema.optionalProperties) {
+         for (const [key, value] of Object.entries(schema.optionalProperties)) {
+            properties[key] = convertSchema(value);
+         }
+      }
+
+      const result: Record<string, unknown> = {
+         type: "object",
+         properties,
+         additionalProperties: false,
+      };
+
+      if (required.length > 0) {
+         result.required = required;
+      }
+
+      return result;
+   }
+
+   // Discriminator form: { discriminator: "type", mapping: { ... } }
+   if (isJTDDiscriminator(schema)) {
+      const oneOf: unknown[] = [];
+
+      for (const [tag, props] of Object.entries(schema.mapping)) {
+         const converted = convertSchema(props) as Record<string, unknown>;
+         // Add the discriminator property
+         const properties = (converted.properties || {}) as Record<string, unknown>;
+         properties[schema.discriminator] = { const: tag };
+
+         const required = ((converted.required as string[]) || []).slice();
+         if (!required.includes(schema.discriminator)) {
+            required.push(schema.discriminator);
+         }
+
+         oneOf.push({
+            ...converted,
+            properties,
+            required,
+         });
+      }
+
+      return { oneOf };
+   }
+
+   // Ref form: { ref: "MyType" } → { $ref: "#/$defs/MyType" }
+   if (isJTDRef(schema)) {
+      return { $ref: `#/$defs/${schema.ref}` };
+   }
+
+   // Empty form: {} → {} (accepts anything)
+   return {};
+}
+
+/**
+ * Detect if a schema is JTD format (vs JSON Schema).
+ *
+ * JTD schemas use: type (primitives), properties, optionalProperties, elements, values, enum, discriminator, ref
+ * JSON Schema uses: type: "object", type: "array", items, additionalProperties, etc.
+ */
+export function isJTDSchema(schema: unknown): boolean {
+   if (schema === null || typeof schema !== "object") {
+      return false;
+   }
+
+   const obj = schema as Record<string, unknown>;
+
+   // JTD-specific keywords
+   if ("elements" in obj) return true;
+   if ("values" in obj) return true;
+   if ("optionalProperties" in obj) return true;
+   if ("discriminator" in obj) return true;
+   if ("ref" in obj) return true;
+
+   // JTD type primitives (JSON Schema doesn't have int32, float64, etc.)
+   if ("type" in obj) {
+      const jtdPrimitives = [
+         "timestamp",
+         "float32",
+         "float64",
+         "int8",
+         "uint8",
+         "int16",
+         "uint16",
+         "int32",
+         "uint32",
+      ];
+      if (jtdPrimitives.includes(obj.type as string)) {
+         return true;
+      }
+   }
+
+   // JTD properties form without type: "object" (JSON Schema requires it)
+   if ("properties" in obj && !("type" in obj)) {
+      return true;
+   }
+
+   return false;
+}
+
+/**
+ * Convert JTD schema to JSON Schema.
+ * If already JSON Schema, returns as-is.
+ */
+export function jtdToJsonSchema(schema: unknown): unknown {
+   if (!isJTDSchema(schema)) {
+      return schema;
+   }
+   return convertSchema(schema);
+}