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

package/src/core/tools/task/worker.ts

@@ -0,0 +1,270 @@
+/**
+ * Worker thread for subagent execution.
+ *
+ * This worker runs in a separate thread via Bun's Worker API. It creates a minimal
+ * AgentSession and forwards events back to the parent thread.
+ *
+ * ## Event Flow
+ *
+ * 1. Parent sends { type: "start", payload } with task config
+ * 2. Worker creates AgentSession and subscribes to events
+ * 3. Worker forwards AgentEvent messages via postMessage
+ * 4. Worker sends { type: "done", exitCode, ... } on completion
+ * 5. Parent can send { type: "abort" } to request cancellation
+ */
+
+import type { Api, Model } from "@mariozechner/pi-ai";
+import type { AgentEvent, ThinkingLevel } from "@oh-my-pi/pi-agent-core";
+import type { AgentSessionEvent } from "../../agent-session";
+import { parseModelPattern, parseModelString } from "../../model-resolver";
+import { createAgentSession, discoverAuthStorage, discoverModels } from "../../sdk";
+import { SessionManager } from "../../session-manager";
+import type { SubagentWorkerRequest, SubagentWorkerResponse, SubagentWorkerStartPayload } from "./worker-protocol";
+
+type PostMessageFn = (message: SubagentWorkerResponse) => void;
+
+const postMessageSafe: PostMessageFn = (message) => {
+	(globalThis as typeof globalThis & { postMessage: PostMessageFn }).postMessage(message);
+};
+
+interface WorkerMessageEvent<T> {
+	data: T;
+}
+
+/** Agent event types to forward to parent (excludes session-only events like compaction) */
+const agentEventTypes = new Set<AgentEvent["type"]>([
+	"agent_start",
+	"agent_end",
+	"turn_start",
+	"turn_end",
+	"message_start",
+	"message_update",
+	"message_end",
+	"tool_execution_start",
+	"tool_execution_update",
+	"tool_execution_end",
+]);
+
+const isAgentEvent = (event: AgentSessionEvent): event is AgentEvent => {
+	return agentEventTypes.has(event.type as AgentEvent["type"]);
+};
+
+let running = false;
+let abortRequested = false;
+let activeSession: { abort: () => Promise<void>; dispose: () => Promise<void> } | null = null;
+
+/**
+ * Resolve model string to Model object with optional thinking level.
+ * Supports both exact "provider/id" format and fuzzy matching ("sonnet", "opus").
+ */
+function resolveModelOverride(
+	override: string | undefined,
+	modelRegistry: { getAvailable: () => Model<Api>[]; find: (provider: string, id: string) => Model<Api> | undefined },
+): { model?: Model<Api>; thinkingLevel?: ThinkingLevel } {
+	if (!override) return {};
+
+	// Try exact "provider/id" format first
+	const parsed = parseModelString(override);
+	if (parsed) {
+		return { model: modelRegistry.find(parsed.provider, parsed.id) };
+	}
+
+	// Fall back to fuzzy pattern matching
+	const result = parseModelPattern(override, modelRegistry.getAvailable());
+	return {
+		model: result.model,
+		thinkingLevel: result.thinkingLevel !== "off" ? result.thinkingLevel : undefined,
+	};
+}
+
+/**
+ * Main task execution function.
+ *
+ * Equivalent to CLI flow:
+ * 1. omp --mode json --non-interactive
+ * 2. --append-system-prompt <agent.systemPrompt>
+ * 3. --tools <toolNames> (if specified)
+ * 4. --model <model> (if specified)
+ * 5. --session <sessionFile> OR --no-session
+ * 6. --prompt <task>
+ *
+ * Environment equivalent:
+ * - OMP_BLOCKED_AGENT: payload.blockedAgent (prevents same-agent recursion)
+ * - OMP_SPAWNS: payload.spawnsEnv (controls nested spawn permissions)
+ */
+async function runTask(payload: SubagentWorkerStartPayload): Promise<void> {
+	const startTime = Date.now();
+	let exitCode = 0;
+	let error: string | undefined;
+	let aborted = false;
+
+	try {
+		// Check for pre-start abort
+		if (abortRequested) {
+			aborted = true;
+			exitCode = 1;
+			return;
+		}
+
+		// Set working directory (CLI does this implicitly)
+		process.chdir(payload.cwd);
+
+		// Discover auth and models (equivalent to CLI's discoverAuthStorage/discoverModels)
+		const authStorage = await discoverAuthStorage();
+		const modelRegistry = await discoverModels(authStorage);
+
+		// Resolve model override (equivalent to CLI's parseModelPattern with --model)
+		const { model, thinkingLevel } = resolveModelOverride(payload.model, modelRegistry);
+
+		// Create session manager (equivalent to CLI's --session or --no-session)
+		const sessionManager = payload.sessionFile
+			? await SessionManager.open(payload.sessionFile)
+			: SessionManager.inMemory(payload.cwd);
+
+		// Create agent session (equivalent to CLI's createAgentSession)
+		// Note: hasUI: false disables interactive features
+		const completionInstruction =
+			"When finished, call the complete tool exactly once. Do not end with a plain-text final answer.";
+
+		const { session } = await createAgentSession({
+			cwd: payload.cwd,
+			authStorage,
+			modelRegistry,
+			model,
+			thinkingLevel,
+			toolNames: payload.toolNames,
+			outputSchema: payload.outputSchema,
+			requireCompleteTool: true,
+			// Append system prompt (equivalent to CLI's --append-system-prompt)
+			systemPrompt: (defaultPrompt) => `${defaultPrompt}\n\n${payload.systemPrompt}\n\n${completionInstruction}`,
+			sessionManager,
+			hasUI: false,
+			// Pass spawn restrictions to nested tasks
+			spawns: payload.spawnsEnv,
+		});
+
+		activeSession = session;
+
+		// Initialize extensions (equivalent to CLI's extension initialization)
+		// Note: Does not support --extension CLI flag or extension CLI flags
+		const extensionRunner = session.extensionRunner;
+		if (extensionRunner) {
+			extensionRunner.initialize({
+				getModel: () => session.model,
+				sendMessageHandler: (message, options) => {
+					session.sendCustomMessage(message, options).catch((e) => {
+						console.error(`Extension sendMessage failed: ${e instanceof Error ? e.message : String(e)}`);
+					});
+				},
+				appendEntryHandler: (customType, data) => {
+					session.sessionManager.appendCustomEntry(customType, data);
+				},
+				getActiveToolsHandler: () => session.getActiveToolNames(),
+				getAllToolsHandler: () => session.getAllToolNames(),
+				setActiveToolsHandler: (toolNamesList: string[]) => session.setActiveToolsByName(toolNamesList),
+			});
+			extensionRunner.onError((err) => {
+				console.error(`Extension error (${err.extensionPath}): ${err.error}`);
+			});
+			await extensionRunner.emit({ type: "session_start" });
+		}
+
+		// Track complete tool calls
+		const MAX_COMPLETE_RETRIES = 3;
+		let completeCalled = false;
+
+		// Subscribe to events and forward to parent (equivalent to --mode json output)
+		session.subscribe((event: AgentSessionEvent) => {
+			if (isAgentEvent(event)) {
+				postMessageSafe({ type: "event", event });
+				// Track when complete tool is called
+				if (event.type === "tool_execution_end" && event.toolName === "complete") {
+					completeCalled = true;
+				}
+			}
+		});
+
+		// Run the prompt (equivalent to --prompt flag)
+		await session.prompt(payload.task);
+
+		// Retry loop if complete was not called
+		let retryCount = 0;
+		while (!completeCalled && retryCount < MAX_COMPLETE_RETRIES && !abortRequested) {
+			retryCount++;
+			const reminder = `<system-reminder>
+CRITICAL: You stopped without calling the complete tool. This is reminder ${retryCount} of ${MAX_COMPLETE_RETRIES}.
+
+You MUST call the complete tool to finish your task. Options:
+1. Call complete with your result data if you have completed the task
+2. Call complete with status="aborted" and an error message if you cannot complete the task
+
+Failure to call complete after ${MAX_COMPLETE_RETRIES} reminders will result in task failure.
+</system-reminder>
+
+Call complete now.`;
+
+			await session.prompt(reminder);
+		}
+
+		// Check if aborted during execution
+		const lastMessage = session.state.messages[session.state.messages.length - 1];
+		if (lastMessage?.role === "assistant" && lastMessage.stopReason === "aborted") {
+			aborted = true;
+			exitCode = 1;
+		}
+	} catch (err) {
+		exitCode = 1;
+		error = err instanceof Error ? err.stack || err.message : String(err);
+	} finally {
+		// Handle abort requested during execution
+		if (abortRequested) {
+			aborted = true;
+			if (exitCode === 0) exitCode = 1;
+		}
+
+		// Cleanup session
+		if (activeSession) {
+			try {
+				await activeSession.dispose();
+			} catch {
+				// Ignore cleanup errors
+			}
+			activeSession = null;
+		}
+
+		// Send completion message to parent
+		postMessageSafe({
+			type: "done",
+			exitCode,
+			durationMs: Date.now() - startTime,
+			error,
+			aborted,
+		});
+	}
+}
+
+/** Handle abort request from parent */
+function handleAbort(): void {
+	abortRequested = true;
+	if (activeSession) {
+		void activeSession.abort();
+	}
+}
+
+// Message handler - receives start/abort commands from parent
+globalThis.addEventListener("message", (event: WorkerMessageEvent<SubagentWorkerRequest>) => {
+	const message = event.data;
+	if (!message) return;
+
+	if (message.type === "abort") {
+		handleAbort();
+		return;
+	}
+
+	if (message.type === "start") {
+		// Only allow one task per worker
+		if (running) return;
+		running = true;
+		void runTask(message.payload);
+	}
+});

package/src/core/tools/web-fetch.ts

@@ -5,6 +5,7 @@ import { Type } from "@sinclair/typebox";
 import { parse as parseHtml } from "node-html-parser";
 import webFetchDescription from "../../prompts/tools/web-fetch.md" with { type: "text" };
 import { logger } from "../logger";
+import type { ToolSession } from "./index";
 
 // =============================================================================
 // Types and Constants
@@ -1239,9 +1240,7 @@ async function handleStackOverflow(url: string, timeout: number): Promise<Render
 		md += `**Score:** ${question.score} · **Answers:** ${question.answer_count}`;
 		md += question.is_answered ? " (Answered)" : "";
 		md += `\n**Tags:** ${question.tags.join(", ")}\n`;
-		md += `**Asked by:** ${question.owner.display_name} · ${
-			new Date(question.creation_date * 1000).toISOString().split("T")[0]
-		}\n\n`;
+		md += `**Asked by:** ${question.owner.display_name} · ${new Date(question.creation_date * 1000).toISOString().split("T")[0]}\n\n`;
 		md += `---\n\n## Question\n\n${htmlToBasicMarkdown(question.body)}\n\n`;
 
 		// Fetch answers
@@ -2270,7 +2269,7 @@ export interface WebFetchToolDetails {
 	notes: string[];
 }
 
-export function createWebFetchTool(_cwd: string): AgentTool<typeof webFetchSchema> {
+export function createWebFetchTool(_session: ToolSession): AgentTool<typeof webFetchSchema> {
 	return {
 		name: "web_fetch",
 		label: "Web Fetch",
@@ -2316,9 +2315,6 @@ export function createWebFetchTool(_cwd: string): AgentTool<typeof webFetchSchem
 	};
 }
 
-/** Default web fetch tool using process.cwd() - for backwards compatibility */
-export const webFetchTool = createWebFetchTool(process.cwd());
-
 // =============================================================================
 // TUI Rendering
 // =============================================================================
@@ -2326,7 +2322,7 @@ export const webFetchTool = createWebFetchTool(process.cwd());
 import type { Component } from "@oh-my-pi/pi-tui";
 import { Text } from "@oh-my-pi/pi-tui";
 import { type Theme, theme } from "../../modes/interactive/theme/theme";
-import type { CustomTool, CustomToolContext, RenderResultOptions } from "../custom-tools/types";
+import type { RenderResultOptions } from "../custom-tools/types";
 
 /** Truncate text to max length with ellipsis */
 function truncate(text: string, maxLen: number, ellipsis: string): string {
@@ -2490,31 +2486,3 @@ export const webFetchToolRenderer = {
 	renderCall: renderWebFetchCall,
 	renderResult: renderWebFetchResult,
 };
-
-type WebFetchParams = { url: string; timeout?: number; raw?: boolean };
-
-/** Web fetch tool as CustomTool (for TUI rendering support) */
-export const webFetchCustomTool: CustomTool<typeof webFetchSchema, WebFetchToolDetails> = {
-	name: "web_fetch",
-	label: "Web Fetch",
-	description: webFetchDescription,
-	parameters: webFetchSchema,
-
-	async execute(
-		toolCallId: string,
-		params: WebFetchParams,
-		_onUpdate,
-		_ctx: CustomToolContext,
-		_signal?: AbortSignal,
-	) {
-		return webFetchTool.execute(toolCallId, params);
-	},
-
-	renderCall(args: WebFetchParams, uiTheme: Theme) {
-		return renderWebFetchCall(args, uiTheme);
-	},
-
-	renderResult(result, options: RenderResultOptions, uiTheme: Theme) {
-		return renderWebFetchResult(result, options, uiTheme);
-	},
-};

package/src/core/tools/web-search/index.ts

@@ -20,6 +20,7 @@ import type { CustomTool, CustomToolContext, RenderResultOptions } from "../../c
 import { callExaTool, findApiKey as findExaKey, formatSearchResults, isSearchResponse } from "../exa/mcp-client";
 import { renderExaCall, renderExaResult } from "../exa/render";
 import type { ExaRenderDetails } from "../exa/types";
+import type { ToolSession } from "../index";
 import { formatAge } from "../render-utils";
 import { findAnthropicAuth } from "./auth";
 import { searchAnthropic } from "./providers/anthropic";
@@ -365,7 +366,7 @@ export const webSearchCustomTool: CustomTool<typeof webSearchSchema, WebSearchRe
 };
 
 /** Factory function for backward compatibility */
-export function createWebSearchTool(_cwd: string): AgentTool<typeof webSearchSchema> {
+export function createWebSearchTool(_session: ToolSession): AgentTool<typeof webSearchSchema> {
 	return webSearchTool;
 }
 

package/src/core/tools/web-search/render.ts

@@ -257,10 +257,7 @@ export function renderWebSearchResult(
 	}
 	if (response.requestId) {
 		metaLines.push(
-			`${theme.fg("muted", "Request:")} ${theme.fg(
-				"text",
-				truncate(response.requestId, MAX_REQUEST_ID_LEN, theme.format.ellipsis),
-			)}`,
+			`${theme.fg("muted", "Request:")} ${theme.fg("text", truncate(response.requestId, MAX_REQUEST_ID_LEN, theme.format.ellipsis))}`,
 		);
 	}
 	if (searchQueries.length > 0) {

package/src/core/tools/write.ts

@@ -5,7 +5,8 @@ import { Type } from "@sinclair/typebox";
 import { getLanguageFromPath, highlightCode, type Theme } from "../../modes/interactive/theme/theme";
 import writeDescription from "../../prompts/tools/write.md" with { type: "text" };
 import type { RenderResultOptions } from "../custom-tools/types";
-import { type FileDiagnosticsResult, type WritethroughCallback, writethroughNoop } from "./lsp/index";
+import type { ToolSession } from "../sdk";
+import { createLspWritethrough, type FileDiagnosticsResult } from "./lsp/index";
 import { resolveToCwd } from "./path-utils";
 import { formatDiagnostics, replaceTabs, shortenPath } from "./render-utils";
 
@@ -14,21 +15,15 @@ const writeSchema = Type.Object({
 	content: Type.String({ description: "Content to write to the file" }),
 });
 
-/** Options for creating the write tool */
-export interface WriteToolOptions {
-	writethrough?: WritethroughCallback;
-}
-
 /** Details returned by the write tool for TUI rendering */
 export interface WriteToolDetails {
 	diagnostics?: FileDiagnosticsResult;
 }
 
-export function createWriteTool(
-	cwd: string,
-	options: WriteToolOptions = {},
-): AgentTool<typeof writeSchema, WriteToolDetails> {
-	const writethrough = options.writethrough ?? writethroughNoop;
+export function createWriteTool(session: ToolSession): AgentTool<typeof writeSchema, WriteToolDetails> {
+	const enableFormat = session.settings?.getLspFormatOnWrite() ?? true;
+	const enableDiagnostics = session.settings?.getLspDiagnosticsOnWrite() ?? true;
+	const writethrough = createLspWritethrough(session.cwd, { enableFormat, enableDiagnostics });
 	return {
 		name: "write",
 		label: "Write",
@@ -39,7 +34,7 @@ export function createWriteTool(
 			{ path, content }: { path: string; content: string },
 			signal?: AbortSignal,
 		) => {
-			const absolutePath = resolveToCwd(path, cwd);
+			const absolutePath = resolveToCwd(path, session.cwd);
 
 			const diagnostics = await writethrough(absolutePath, content, signal);
 
@@ -64,9 +59,6 @@ export function createWriteTool(
 	};
 }
 
-/** Default write tool using process.cwd() - for backwards compatibility */
-export const writeTool = createWriteTool(process.cwd());
-
 // =============================================================================
 // TUI Renderer
 // =============================================================================

package/src/discovery/helpers.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from "vitest";
+import { describe, expect, test } from "bun:test";
 import { parseFrontmatter } from "./helpers";
 
 describe("parseFrontmatter", () => {

package/src/index.ts

@@ -81,6 +81,8 @@ export { ModelRegistry } from "./core/model-registry";
 export type { PromptTemplate } from "./core/prompt-templates";
 // SDK for programmatic usage
 export {
+	// Tool factories
+	BUILTIN_TOOLS,
 	type BuildSystemPromptOptions,
 	buildSystemPrompt,
 	type CreateAgentSessionOptions,
@@ -88,14 +90,12 @@ export {
 	// Factory
 	createAgentSession,
 	createBashTool,
-	// Tool factories (for custom cwd)
-	createCodingTools,
 	createEditTool,
 	createFindTool,
 	createGrepTool,
 	createLsTool,
-	createReadOnlyTools,
 	createReadTool,
+	createTools,
 	createWriteTool,
 	// Discovery
 	discoverAuthStorage,
@@ -107,8 +107,7 @@ export {
 	discoverPromptTemplates,
 	discoverSkills,
 	loadSettings,
-	// Pre-built tools (use process.cwd())
-	readOnlyTools,
+	type ToolSession,
 } from "./core/sdk";
 export {
 	type BranchSummaryEntry,
@@ -154,27 +153,17 @@ export {
 } from "./core/skills";
 // Slash commands
 export { type FileSlashCommand, loadSlashCommands as discoverSlashCommands } from "./core/slash-commands";
-// Tools
+// Tools (detail types only - factories exported from sdk)
 export {
 	type BashToolDetails,
-	bashTool,
-	type CodingToolsOptions,
-	codingTools,
-	editTool,
 	type FindToolDetails,
-	findTool,
 	type GitToolDetails,
 	type GrepToolDetails,
 	gitTool,
-	grepTool,
 	type LsToolDetails,
-	lsTool,
 	type ReadToolDetails,
-	readTool,
 	type TruncationResult,
 	type WriteToolDetails,
-	type WriteToolOptions,
-	writeTool,
 } from "./core/tools/index";
 export type { FileDiagnosticsResult } from "./core/tools/lsp/index";
 // Main entry point

package/src/main.ts

@@ -24,7 +24,6 @@ import { SessionManager } from "./core/session-manager";
 import { SettingsManager } from "./core/settings-manager";
 import { resolvePromptInput } from "./core/system-prompt";
 import { printTimings, time } from "./core/timings";
-import { allTools } from "./core/tools/index";
 import { runMigrations, showDeprecationWarnings } from "./migrations";
 import { InteractiveMode, installTerminalCrashHandlers, runPrintMode, runRpcMode } from "./modes/index";
 import { initTheme, stopThemeWatcher } from "./modes/interactive/theme/theme";
@@ -210,7 +209,9 @@ async function buildSessionOptions(
 	modelRegistry: ModelRegistry,
 	settingsManager: SettingsManager,
 ): Promise<CreateAgentSessionOptions> {
-	const options: CreateAgentSessionOptions = {};
+	const options: CreateAgentSessionOptions = {
+		cwd: parsed.cwd ?? process.cwd(),
+	};
 
 	// Auto-discover SYSTEM.md if no CLI system prompt provided
 	const systemPromptSource = parsed.systemPrompt ?? discoverSystemPromptFile();
@@ -263,8 +264,7 @@ async function buildSessionOptions(
 
 	// Tools
 	if (parsed.tools) {
-		options.tools = parsed.tools.map((name) => allTools[name]);
-		options.explicitTools = parsed.tools;
+		options.toolNames = parsed.tools;
 	}
 
 	// Skills

package/src/modes/interactive/theme/theme.ts

@@ -1367,9 +1367,9 @@ export class Theme {
 		return (str: string) => this.fg("bashMode", str);
 	}
 
-	// -------------------------------------------------------------------------
+	// ============================================================================
 	// Symbol Methods
-	// -------------------------------------------------------------------------
+	// ============================================================================
 
 	/**
 	 * Get a symbol by key.
@@ -1392,9 +1392,9 @@ export class Theme {
 		return this.symbolPreset;
 	}
 
-	// -------------------------------------------------------------------------
+	// ============================================================================
 	// Symbol Category Accessors
-	// -------------------------------------------------------------------------
+	// ============================================================================
 
 	get status() {
 		return {

package/src/prompts/task.md

@@ -1,57 +1,14 @@
----
-name: task
-description: General-purpose subagent with full capabilities for delegated multi-step tasks
-spawns: explore
-model: default
----
-
-You are a worker agent for delegated tasks. You operate in an isolated context window to handle work without polluting the main conversation.
-
-Do what has been asked; nothing more, nothing less. Work autonomously using all available tools.
-
-Your strengths:
-
-- Searching for code, configurations, and patterns across large codebases
-- Analyzing multiple files to understand system architecture
-- Investigating complex questions that require exploring many files
-- Performing multi-step research and implementation tasks
-
-Guidelines:
-
-- Persist until the task is fully resolved end-to-end when feasible.
-- Verify with tools; ask for clarification when required.
-- For file searches: Use grep/glob when you need to search broadly. Use read when you know the specific file path.
-- For analysis: Start broad and narrow down. Use multiple search strategies if the first doesn't yield results.
-- Be thorough: Check multiple locations, consider different naming conventions, look for related files.
-- When spawning subagents with the Task tool, include a short, user-facing `description` for each task (5-8 words) that summarizes the approach.
-- NEVER create files unless absolutely necessary. ALWAYS prefer editing existing files.
-- NEVER proactively create documentation files (\*.md) or README files unless explicitly requested.
-- Any file paths in your response MUST be absolute. Do NOT use relative paths.
-- Include relevant code snippets in your final response.
-
-Output format when finished:
-
-## Completed
-
-What was done.
-
-## Files Changed
-
-- `/absolute/path/to/file.ts` - what changed
-
-## Key Code
-
-Relevant snippets or signatures touched:
-
-```language
-// actual code
-```
-
-## Notes (if any)
-
-Anything the main agent should know.
-
-If handing off to another agent (e.g. reviewer), include:
-
-- Exact file paths changed
-- Key functions/types touched (short list)
+You are a worker agent for delegated tasks in an isolated context. Finish only the assigned work and return the minimum useful result.
+
+Principles:
+
+- Be concise. No filler, repetition, or tool transcripts.
+- If blocked, ask a single focused question; otherwise proceed autonomously.
+- Prefer narrow search (grep/glob) then read only needed ranges.
+- Avoid full-file reads unless necessary.
+- NEVER create files unless absolutely required. Prefer edits to existing files.
+- NEVER create documentation files (\*.md) unless explicitly requested.
+- Any file paths in your response MUST be absolute.
+- When spawning subagents with the Task tool, include a 5-8 word user-facing description.
+- Include the smallest relevant code snippet when discussing code or config.
+- Follow the main agent's instructions.

package/src/prompts/tools/output.md

@@ -1,16 +1,16 @@
-# TaskOutput
-
 Retrieves complete output from background tasks spawned with the Task tool.
 
 ## When to Use
 
 Use TaskOutput when:
+
 - Task tool returns truncated preview with "Output truncated" message
 - You need full output to debug errors or analyze detailed results
 - Task tool's summary shows substantial line/character counts but preview is incomplete
 - You're analyzing multi-step task output requiring full context
 
 Do NOT use when:
+
 - Task preview already shows complete output (no truncation indicator)
 - Summary alone answers your question
 
@@ -21,7 +21,8 @@ Do NOT use when:
   - `"raw"` (default): Full output with ANSI codes preserved
   - `"json"`: Structured object with metadata
   - `"stripped"`: Plain text with ANSI codes removed for parsing
+- `query` (optional): jq-like query for JSON outputs (e.g., `.result.items[0].name`)
 - `offset` (optional): Line number to start reading from (1-indexed)
 - `limit` (optional): Maximum number of lines to read
 
-Use offset/limit for line ranges to reduce context usage on large outputs.
+Use offset/limit for line ranges to reduce context usage on large outputs. Use `query` for JSON outputs (for example, subagent `complete` results).