@oh-my-pi/pi-coding-agent 1.341.0 → 2.0.1337

package/src/core/tools/task/bundled-agents/reviewer.md

@@ -1,59 +1,74 @@
 ---
 name: reviewer
-description: Expert code reviewer for PRs and implementation changes
-tools: read, grep, glob, ls, bash
+description: Code review specialist for quality and security analysis
+tools: read, grep, find, ls, bash, task, report_finding, submit_review
 model: pi/slow, gpt-5.2-codex, gpt-5.2, codex, gpt
 ---
 
-You are an expert code reviewer. Analyze code changes and provide thorough reviews.
+You are acting as a reviewer for a proposed code change made by another engineer.
 
-## For PR Reviews
+Bash is for read-only commands only: `git diff`, `git log`, `git show`, `gh pr diff`. Do NOT modify files or run builds.
 
-1. If no PR number provided, run `gh pr list` to show open PRs
-2. If PR number provided:
-   - `gh pr view <number>` to get PR details
-   - `gh pr diff <number>` to get the diff
-3. Analyze changes and provide review
+# Review Strategy
 
-## For Implementation Reviews
+1. Run `git diff` (or `gh pr diff <number>`) to see the changes
+2. Read the modified files for full context
+3. For large changes spanning multiple files/modules, use `task` with `explore` agents in parallel to gather context faster
+4. Analyze for bugs, security issues, and code quality problems
+5. Use `report_finding` for each issue found
+6. Use `submit_review` to provide final verdict
 
-When reviewing implementation output from another agent:
+# Parallelization
 
-1. Read the files that were changed
-2. Understand the context and requirements
-3. Analyze the implementation quality
+For reviews touching many files, spawn `explore` agents to research in parallel:
+- Each agent can investigate a different module or concern
+- Example: one explores test coverage, another checks related implementations
+- Gather their findings, then synthesize into your review
 
-## Review Focus
+# What to Flag
 
-- **Correctness**: Does the code do what it's supposed to?
-- **Project Conventions**: Does it follow existing patterns?
-- **Performance**: Any performance implications?
-- **Test Coverage**: Are changes adequately tested?
-- **Security**: Any security considerations?
-- **Edge Cases**: Are edge cases handled?
+Only flag issues where ALL of these apply:
 
-## Output Format
+1. It meaningfully impacts the accuracy, performance, security, or maintainability of the code
+2. The bug is discrete and actionable (not a general issue or combination of multiple issues)
+3. Fixing it doesn't demand rigor not present elsewhere in the codebase
+4. The bug was introduced in this commit (don't flag pre-existing bugs)
+5. The author would likely fix the issue if made aware of it
+6. The bug doesn't rely on unstated assumptions about the codebase or author's intent
+7. You can identify specific code that is provably affected (speculation is not enough)
+8. The issue is clearly not an intentional change by the author
 
-### Overview
+# Priority Levels
 
-What the changes do.
+- **P0**: Drop everything to fix. Blocking release, operations, or major usage. Only use for universal issues that do not depend on assumptions about inputs.
+- **P1**: Urgent. Should be addressed in the next cycle.
+- **P2**: Normal. To be fixed eventually.
+- **P3**: Low. Nice to have.
 
-### Strengths
+# Comment Guidelines
 
-What's done well.
+1. Be clear about WHY the issue is a bug
+2. Communicate severity appropriately - don't overstate
+3. Keep body to one paragraph max
+4. Code snippets should be ≤3 lines, wrapped in markdown code tags
+5. Clearly state what conditions are necessary for the bug to arise
+6. Tone: matter-of-fact, not accusatory or overly positive
+7. Write so the author can immediately grasp the idea without close reading
+8. Avoid flattery and phrases like "Great job...", "Thanks for..."
 
-### Issues
+# CRITICAL
 
-Problems that should be fixed (with file:line references).
+You MUST call `submit_review` before ending your response, even if you found no issues.
+The review is only considered complete when `submit_review` is called.
+Failure to call `submit_review` means the review was not submitted.
 
-### Suggestions
+# Output
 
-Improvements to consider (optional, not blocking).
+- Use `report_finding` for each issue. Continue until you've listed every qualifying finding.
+- If there is no finding that a person would definitely want to fix, prefer outputting no findings.
+- Ignore trivial style unless it obscures meaning or violates documented standards.
+- Use `submit_review` at the end with your overall verdict:
+  - **correct**: Existing code and tests will not break, patch is free of bugs and blocking issues
+  - **incorrect**: Has bugs or blocking issues that must be addressed
 
-### Verdict
-
-- ✅ **Approve**: Ready to merge/complete
-- 🔄 **Request Changes**: Issues must be addressed
-- 💬 **Comment**: Minor suggestions, can proceed
-
-Keep reviews concise but thorough. Focus on substance over style nitpicks.
+Ignore non-blocking issues (style, formatting, typos, documentation, nits) when determining correctness.

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

@@ -13,8 +13,8 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { loadBundledAgents } from "./agents.js";
-import type { AgentDefinition, AgentSource } from "./types.js";
+import { loadBundledAgents } from "./agents";
+import type { AgentDefinition, AgentSource } from "./types";
 
 /** Result of agent discovery */
 export interface DiscoveryResult {

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

@@ -10,15 +10,17 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import * as readline from "node:readline";
-import { resolveModelPattern } from "./model-resolver.js";
+import { ensureArtifactsDir, getArtifactPaths } from "./artifacts";
+import { resolveModelPattern } from "./model-resolver";
+import { subprocessToolRegistry } from "./subprocess-tool-registry";
 import {
 	type AgentDefinition,
 	type AgentProgress,
 	MAX_OUTPUT_BYTES,
 	MAX_OUTPUT_LINES,
-	PI_NO_SUBAGENTS_ENV,
+	PI_BLOCKED_AGENT_ENV,
 	type SingleResult,
-} from "./types.js";
+} from "./types";
 
 /** pi command: 'pi.cmd' on Windows, 'pi' elsewhere */
 const PI_CMD = process.platform === "win32" ? "pi.cmd" : "pi";
@@ -166,6 +168,23 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 	// Build full task with context
 	const fullTask = context ? `${context}\n\n${task}` : task;
 
+	// Set up artifact paths and write input file upfront if artifacts dir provided
+	let artifactPaths: { inputPath: string; outputPath: string; jsonlPath: string } | undefined;
+	let subtaskSessionFile: string | undefined;
+
+	if (options.artifactsDir) {
+		ensureArtifactsDir(options.artifactsDir);
+		artifactPaths = getArtifactPaths(options.artifactsDir, agent.name, index);
+		subtaskSessionFile = artifactPaths.jsonlPath;
+
+		// Write input file immediately (real-time visibility)
+		try {
+			fs.writeFileSync(artifactPaths.inputPath, fullTask, "utf-8");
+		} catch {
+			// Non-fatal, continue without input artifact
+		}
+	}
+
 	// Build args
 	const args: string[] = ["--mode", "json", "--non-interactive"];
 
@@ -183,8 +202,10 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 		args.push("--model", resolvedModel);
 	}
 
-	// Add session options
-	if (options.sessionFile) {
+	// Add session options - use subtask-specific session file for real-time streaming
+	if (subtaskSessionFile) {
+		args.push("--session", subtaskSessionFile);
+	} else if (options.sessionFile) {
 		args.push("--session", options.sessionFile);
 	} else {
 		args.push("--no-session");
@@ -193,10 +214,10 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 	// Add task as prompt
 	args.push("--prompt", fullTask);
 
-	// Set up environment
+	// Set up environment - block same-agent recursion unless explicitly recursive
 	const env = { ...process.env };
 	if (!agent.recursive) {
-		env[PI_NO_SUBAGENTS_ENV] = "1";
+		env[PI_BLOCKED_AGENT_ENV] = agent.name;
 	}
 
 	// Spawn subprocess
@@ -211,6 +232,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 	let stderr = "";
 	let finalOutput = "";
 	let resolved = false;
+	let pendingTermination = false; // Set when shouldTerminate fires, wait for message_end
 	const jsonlEvents: string[] = [];
 
 	// Handle abort signal
@@ -242,7 +264,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 					progress.currentToolStartMs = now;
 					break;
 
-				case "tool_execution_end":
+				case "tool_execution_end": {
 					if (progress.currentTool) {
 						progress.recentTools.unshift({
 							tool: progress.currentTool,
@@ -257,24 +279,73 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 					progress.currentTool = undefined;
 					progress.currentToolArgs = undefined;
 					progress.currentToolStartMs = undefined;
+
+					// Check for registered subprocess tool handler
+					const handler = subprocessToolRegistry.getHandler(event.toolName);
+					if (handler) {
+						// Extract data using handler
+						if (handler.extractData) {
+							const data = handler.extractData({
+								toolName: event.toolName,
+								toolCallId: event.toolCallId,
+								args: event.args,
+								result: event.result,
+								isError: event.isError,
+							});
+							if (data !== undefined) {
+								progress.extractedToolData = progress.extractedToolData || {};
+								progress.extractedToolData[event.toolName] = progress.extractedToolData[event.toolName] || [];
+								progress.extractedToolData[event.toolName].push(data);
+							}
+						}
+
+						// Check if handler wants to terminate subprocess
+						if (
+							handler.shouldTerminate?.({
+								toolName: event.toolName,
+								toolCallId: event.toolCallId,
+								args: event.args,
+								result: event.result,
+								isError: event.isError,
+							})
+						) {
+							// Don't kill immediately - wait for message_end to get token counts
+							pendingTermination = true;
+							// Safety timeout in case message_end never arrives
+							setTimeout(() => {
+								if (!resolved) {
+									resolved = true;
+									proc.kill("SIGTERM");
+								}
+							}, 2000);
+						}
+					}
+					break;
+				}
+
+				case "message_update": {
+					// Extract text for progress display only (replace, don't accumulate)
+					const updateContent = event.message?.content || event.content;
+					if (updateContent && Array.isArray(updateContent)) {
+						const allText: string[] = [];
+						for (const block of updateContent) {
+							if (block.type === "text" && block.text) {
+								const lines = block.text.split("\n").filter((l: string) => l.trim());
+								allText.push(...lines);
+							}
+						}
+						// Show last 8 lines from current state (not accumulated)
+						progress.recentOutput = allText.slice(-8).reverse();
+					}
 					break;
+				}
 
-				case "message_update":
 				case "message_end": {
-					// Extract text content for recent output (prefer message.content, fallback to event.content)
+					// Extract final text content from completed message
 					const messageContent = event.message?.content || event.content;
 					if (messageContent && Array.isArray(messageContent)) {
 						for (const block of messageContent) {
 							if (block.type === "text" && block.text) {
-								const lines = block.text.split("\n").filter((l: string) => l.trim());
-								for (const l of lines) {
-									if (!progress.recentOutput.includes(l)) {
-										progress.recentOutput.unshift(l);
-										if (progress.recentOutput.length > 8) {
-											progress.recentOutput.pop();
-										}
-									}
-								}
 								output += block.text;
 							}
 						}
@@ -282,7 +353,13 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 					// Extract usage (prefer message.usage, fallback to event.usage)
 					const messageUsage = event.message?.usage || event.usage;
 					if (messageUsage) {
-						progress.tokens = (messageUsage.input_tokens || 0) + (messageUsage.output_tokens || 0);
+						// Accumulate tokens across messages (not overwrite)
+						progress.tokens += (messageUsage.input_tokens || 0) + (messageUsage.output_tokens || 0);
+					}
+					// If pending termination, now we have tokens - terminate
+					if (pendingTermination && !resolved) {
+						resolved = true;
+						proc.kill("SIGTERM");
 					}
 					break;
 				}
@@ -304,7 +381,8 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 			}
 
 			progress.durationMs = now - startTime;
-			onProgress?.(progress);
+			// Clone progress object before passing to callback to prevent mutation during render
+			onProgress?.({ ...progress });
 		} catch {
 			// Ignore non-JSON lines
 		}
@@ -316,16 +394,35 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 		stderr += stderrDecoder.decode(chunk, { stream: true });
 	});
 
-	// Wait for process to exit
+	// Wait for readline to finish BEFORE resolving
 	const exitCode = await new Promise<number>((resolve) => {
-		proc.on("close", (code) => {
-			resolved = true;
-			resolve(code ?? 1);
+		let code: number | null = null;
+		let rlClosed = false;
+		let procClosed = false;
+
+		const maybeResolve = () => {
+			if (rlClosed && procClosed) {
+				resolved = true;
+				resolve(code ?? 1);
+			}
+		};
+
+		rl.on("close", () => {
+			rlClosed = true;
+			maybeResolve();
+		});
+
+		proc.on("close", (c) => {
+			code = c;
+			procClosed = true;
+			maybeResolve();
 		});
+
 		proc.on("error", (err) => {
-			resolved = true;
 			stderr += `\nProcess error: ${err.message}`;
-			resolve(1);
+			code = 1;
+			procClosed = true;
+			maybeResolve();
 		});
 	});
 
@@ -344,8 +441,24 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 	const rawOutput = finalOutput || output;
 	const { text: truncatedOutput, truncated } = truncateOutput(rawOutput);
 
+	// Write output artifact (input and jsonl already written in real-time)
+	// Compute output metadata for Output tool integration
+	let outputMeta: { lineCount: number; charCount: number } | undefined;
+	if (artifactPaths) {
+		try {
+			fs.writeFileSync(artifactPaths.outputPath, rawOutput, "utf-8");
+			outputMeta = {
+				lineCount: rawOutput.split("\n").length,
+				charCount: rawOutput.length,
+			};
+		} catch {
+			// Non-fatal
+		}
+	}
+
 	// Update final progress
-	progress.status = exitCode === 0 ? "completed" : "failed";
+	const wasAborted = signal?.aborted ?? false;
+	progress.status = wasAborted ? "aborted" : exitCode === 0 ? "completed" : "failed";
 	progress.durationMs = Date.now() - startTime;
 	onProgress?.(progress);
 
@@ -362,6 +475,10 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 		tokens: progress.tokens,
 		modelOverride,
 		error: exitCode !== 0 && stderr ? stderr : undefined,
+		aborted: wasAborted,
 		jsonlEvents,
+		artifactPaths,
+		extractedToolData: progress.extractedToolData,
+		outputMeta,
 	};
 }

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

@@ -14,33 +14,50 @@
  */
 
 import type { AgentTool } from "@oh-my-pi/pi-agent-core";
-import type { Theme } from "../../../modes/interactive/theme/theme.js";
-import { cleanupTempDir, createTempArtifactsDir, getArtifactsDir, writeArtifacts } from "./artifacts.js";
-import { discoverAgents, getAgent } from "./discovery.js";
-import { runSubprocess } from "./executor.js";
-import { mapWithConcurrencyLimit } from "./parallel.js";
-import { formatDuration, renderCall, renderResult } from "./render.js";
+import type { Theme } from "../../../modes/interactive/theme/theme";
+import { cleanupTempDir, createTempArtifactsDir, getArtifactsDir } from "./artifacts";
+import { discoverAgents, getAgent } from "./discovery";
+import { runSubprocess } from "./executor";
+import { mapWithConcurrencyLimit } from "./parallel";
+import { formatDuration, renderCall, renderResult } from "./render";
 import {
 	type AgentProgress,
 	MAX_AGENTS_IN_DESCRIPTION,
 	MAX_CONCURRENCY,
 	MAX_PARALLEL_TASKS,
+	PI_BLOCKED_AGENT_ENV,
 	PI_NO_SUBAGENTS_ENV,
 	type TaskToolDetails,
 	taskSchema,
-} from "./types.js";
+} from "./types";
+
+// Import review tools for side effects (registers subprocess tool handlers)
+import "../review";
+
+/** Format byte count for display */
+function formatBytes(bytes: number): string {
+	if (bytes < 1024) return `${bytes}B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}K`;
+	return `${(bytes / (1024 * 1024)).toFixed(1)}M`;
+}
 
 /** Session context interface */
 interface SessionContext {
 	getSessionFile: () => string | null;
 }
 
+/** Task tool options */
+interface TaskToolOptions {
+	/** Set of available tool names (for cross-tool awareness) */
+	availableTools?: Set<string>;
+}
+
 // Re-export types and utilities
-export { loadBundledAgents as BUNDLED_AGENTS } from "./agents.js";
-export { discoverCommands, expandCommand, getCommand } from "./commands.js";
-export { discoverAgents, getAgent } from "./discovery.js";
-export type { AgentDefinition, AgentProgress, SingleResult, TaskParams, TaskToolDetails } from "./types.js";
-export { taskSchema } from "./types.js";
+export { loadBundledAgents as BUNDLED_AGENTS } from "./agents";
+export { discoverCommands, expandCommand, getCommand } from "./commands";
+export { discoverAgents, getAgent } from "./discovery";
+export type { AgentDefinition, AgentProgress, SingleResult, TaskParams, TaskToolDetails } from "./types";
+export { taskSchema } from "./types";
 
 /**
  * Build dynamic tool description listing available agents.
@@ -168,8 +185,10 @@ function buildDescription(cwd: string): string {
 export function createTaskTool(
 	cwd: string,
 	sessionContext?: SessionContext,
+	options?: TaskToolOptions,
 ): AgentTool<typeof taskSchema, TaskToolDetails, Theme> {
-	// Check if subagents are inhibited (recursion prevention)
+	const hasOutputTool = options?.availableTools?.has("output") ?? false;
+	// Check if subagents are completely inhibited (legacy recursion prevention)
 	if (process.env[PI_NO_SUBAGENTS_ENV]) {
 		return {
 			name: "task",
@@ -187,6 +206,9 @@ export function createTaskTool(
 		};
 	}
 
+	// Check for same-agent blocking (allows other agent types)
+	const blockedAgent = process.env[PI_BLOCKED_AGENT_ENV];
+
 	return {
 		name: "task",
 		label: "Task",
@@ -258,7 +280,31 @@ export function createTaskTool(
 			};
 
 			try {
-				const tasks = params.tasks;
+				let tasks = params.tasks;
+				let skippedSelfRecursion = 0;
+
+				// Filter out blocked agent (self-recursion prevention)
+				if (blockedAgent) {
+					const blockedTasks = tasks.filter((t) => t.agent === blockedAgent);
+					tasks = tasks.filter((t) => t.agent !== blockedAgent);
+					skippedSelfRecursion = blockedTasks.length;
+
+					if (skippedSelfRecursion > 0 && tasks.length === 0) {
+						return {
+							content: [
+								{
+									type: "text",
+									text: `Cannot spawn ${blockedAgent} agent from within itself (recursion prevention). Use a different agent type.`,
+								},
+							],
+							details: {
+								projectAgentsDir,
+								results: [],
+								totalDurationMs: Date.now() - startTime,
+							},
+						};
+					}
+				}
 
 				// Validate all agents exist
 				for (const task of tasks) {
@@ -316,40 +362,42 @@ export function createTaskTool(
 						artifactsDir: effectiveArtifactsDir,
 						signal,
 						onProgress: (progress) => {
-							progressMap.set(index, progress);
+							progressMap.set(index, structuredClone(progress));
 							emitProgress();
 						},
 					});
 				});
 
-				// Write artifacts
+				// Collect output paths (artifacts already written by executor in real-time)
 				const outputPaths: string[] = [];
 				for (const result of results) {
-					const fullTask = context ? `${context}\n\n${result.task}` : result.task;
-					const paths = await writeArtifacts(
-						effectiveArtifactsDir,
-						result.agent,
-						result.index,
-						fullTask,
-						result.output,
-						result.jsonlEvents,
-					);
-					outputPaths.push(paths.outputPath);
-					result.artifactPaths = paths;
+					if (result.artifactPaths) {
+						outputPaths.push(result.artifactPaths.outputPath);
+					}
 				}
 
 				// Build final output - match plugin format
 				const successCount = results.filter((r) => r.exitCode === 0).length;
 				const totalDuration = Date.now() - startTime;
 
-				const summaries = results.map((r, i) => {
+				const summaries = results.map((r) => {
 					const status = r.exitCode === 0 ? "completed" : `failed (exit ${r.exitCode})`;
 					const output = r.output.trim() || r.stderr.trim() || "(no output)";
 					const preview = output.split("\n").slice(0, 5).join("\n");
-					return `[${r.agent}] ${status} → ${outputPaths[i]}\n${preview}`;
+					// Include output metadata and ID; include path only if Output tool unavailable (for Read fallback)
+					const outputId = `${r.agent}_${r.index}`;
+					const meta = r.outputMeta
+						? ` [${r.outputMeta.lineCount} lines, ${formatBytes(r.outputMeta.charCount)}]`
+						: "";
+					const pathInfo = !hasOutputTool && r.artifactPaths?.outputPath ? ` (${r.artifactPaths.outputPath})` : "";
+					return `[${r.agent}] ${status}${meta} → ${outputId}${pathInfo}\n${preview}`;
 				});
 
-				const summary = `${successCount}/${results.length} succeeded [${formatDuration(totalDuration)}]\n\n${summaries.join("\n\n---\n\n")}`;
+				const skippedNote =
+					skippedSelfRecursion > 0
+						? ` (${skippedSelfRecursion} ${blockedAgent} task${skippedSelfRecursion > 1 ? "s" : ""} skipped - self-recursion blocked)`
+						: "";
+				const summary = `${successCount}/${results.length} succeeded${skippedNote} [${formatDuration(totalDuration)}]\n\n${summaries.join("\n\n---\n\n")}`;
 
 				// Cleanup temp directory if used
 				if (tempArtifactsDir) {