@fyeeme/pi-review 1.0.0

package/skills/simplify/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: simplify
+description: "Review the changed code for reuse, simplification, efficiency, and altitude cleanups, then apply the fixes. Quality only — it does not hunt for bugs; use /code-review for that. v2 (from Claude Code CLI v2.1.223) — 4 cleanup agents fan out in parallel when context allows, else a single-pass inline cleanup; either way the fixes are applied to the working tree."
+---
+
+<!--
+  Origin: Claude Code built-in skill `/simplify` (CLI v2.1.223), reverse-
+  engineered from bin/claude.exe strings. Pi registers it as /code-simplify.
+
+  Lineage:
+    v2.1.220 → the first reconstruction         (v1)
+    v2.1.223 → verified 2026-08-06 against bin/claude.exe strings: skill body
+               (intro, Phase 0, the 4 cleanup angles, Phase 2 apply) and the
+               PARALLEL/SINGLE-PASS split are unchanged vs v2.1.220. The 4
+               angle bodies are shared verbatim with code-review's cleanup
+               angles (same source variables in the binary).
+
+  Bundled: ships inside the pi-review extension (skills/simplify/SKILL.md).
+
+  Invocation: /code-simplify [<target>]
+    target = file path | PR number | branch name
+
+  ════════════════════════════════════════════════════════════════════════
+  Pi ADAPTATIONS (differ from the CC runtime)
+  ════════════════════════════════════════════════════════════════════════
+    1. Fan-out tool — CC uses the Agent tool; Pi uses the `subagent` tool
+       (mode: parallel). Where CC says "the Agent tool", read `subagent`.
+    2. Mode guard  — CC's _Yo has two clauses: (a) spawn-depth — single-pass when
+       agent depth >= CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH (default 3); (b) the
+       Agent tool must be in the allowlist. On Pi: (a) is N/A — the `subagent`
+       tool spawns a fresh subprocess (always depth 0), so depth never accumulates
+       — so decideSimplifyMode substitutes a context-fraction heuristic
+       (tokens/contextWindow >= 0.8 → single-pass), a Pi addition NOT a mirror of
+       _Yo; (b) is mirrored as "the `subagent` tool must be registered". The
+       decision is made DETERMINISTICALLY by the /code-simplify handler — it can
+       read ctx.getContextUsage(), which a pure-prompt skill cannot — and announced
+       in the trigger message; this skill just provides the two mode bodies.
+    3. Command     — CC: /simplify; Pi: /code-simplify.
+
+  Prerequisite: the `subagent` tool (provided by the pi-review extension) for
+                PARALLEL MODE. SINGLE-PASS MODE runs standalone.
+-->
+
+You are improving the quality of the changed code, not hunting for bugs. Review
+it for reuse, simplification, efficiency, and altitude issues, then fix what you
+find. Do not look for correctness bugs — that is what `/code-review` is for.
+
+The `/code-simplify` handler has already chosen the mode (PARALLEL or
+SINGLE-PASS) from real context usage and announced it in the trigger message.
+Follow the body that matches; do not fake the mode you weren't asked to run.
+
+## Phase 0 — Gather the diff
+
+Run `git diff @{upstream}...HEAD` (or `git diff main...HEAD` / `git diff HEAD~1`
+if there's no upstream) to get the unified diff under review. If there are
+uncommitted changes, or the range diff is empty, also run `git diff HEAD` and
+include the working-tree changes in scope — the review often runs before the
+commit. If a PR number, branch name, or file path was passed as an argument,
+review that target instead. Treat this diff as the review scope.
+
+---
+
+# PARALLEL MODE  (subagent tool available AND context not near-full)
+
+`/code-simplify → 4 cleanup agents in parallel → apply the fixes`
+
+## Phase 1 — Review (4 cleanup agents in parallel)
+
+Launch **4 independent review agents** via the `subagent` tool, all in a single
+message so they run concurrently (mode: parallel). Pass each agent the diff and
+one of the four angles below. Each returns its findings with `file`, `line`, a
+one-line `summary`, and the concrete cost (what is duplicated, wasted, or harder
+to maintain).
+
+### Reuse
+Flag new code that re-implements something the codebase already has — Grep
+shared/utility modules and files adjacent to the change, and name the existing
+helper to call instead.
+
+### Simplification
+Flag unnecessary complexity the diff adds: redundant or derivable state,
+copy-paste with slight variation, deep nesting, dead code left behind. Name the
+simpler form that does the same job.
+
+### Efficiency
+Flag wasted work the diff introduces: redundant computation or repeated I/O,
+independent operations run sequentially, blocking work added to startup or hot
+paths. Also flag long-lived objects built from closures or captured environments
+— they keep the entire enclosing scope alive for the object's lifetime (a memory
+leak when that scope holds large values); prefer a class/struct that copies only
+the fields it needs. Name the cheaper alternative.
+
+### Altitude
+Check that each change is implemented at the right depth, not as a fragile
+bandaid. Special cases layered on shared infrastructure are a sign the fix isn't
+deep enough — prefer generalizing the underlying mechanism over adding special
+cases.
+
+## Phase 2 — Apply the fixes
+
+Wait for all four agents to complete, dedup findings that point at the same line
+or mechanism, and fix each remaining one directly. Skip any finding whose fix
+would change intended behavior, require changes well outside the reviewed diff,
+or that you judge to be a false positive — note the skip rather than arguing
+with it. Finish with a brief summary of what was fixed and what was skipped (or
+confirm the code was already clean).
+
+---
+
+# SINGLE-PASS MODE  (subagent tool unavailable OR context near-full)
+
+`/code-simplify → subagent tool unavailable → single-pass inline cleanup → apply the fixes`
+
+The `subagent` tool isn't available in this context (or context is near-full), so
+the usual 4-agent fan-out can't run. Work through all four angles below yourself,
+in this same context, in one pass — do not skip an angle for lack of fan-out.
+
+## Phase 1 — Review (4 cleanup angles, single pass)
+
+Review the diff against each angle below in turn. For each, note findings with
+`file`, `line`, a one-line `summary`, and the concrete cost (what is duplicated,
+wasted, or harder to maintain).
+
+### Reuse
+Flag new code that re-implements something the codebase already has — Grep
+shared/utility modules and files adjacent to the change, and name the existing
+helper to call instead.
+
+### Simplification
+Flag unnecessary complexity the diff adds: redundant or derivable state,
+copy-paste with slight variation, deep nesting, dead code left behind. Name the
+simpler form that does the same job.
+
+### Efficiency
+Flag wasted work the diff introduces: redundant computation or repeated I/O,
+independent operations run sequentially, blocking work added to startup or hot
+paths. Also flag long-lived objects built from closures or captured environments
+— they keep the entire enclosing scope alive for the object's lifetime (a memory
+leak when that scope holds large values); prefer a class/struct that copies only
+the fields it needs. Name the cheaper alternative.
+
+### Altitude
+Check that each change is implemented at the right depth, not as a fragile
+bandaid. Special cases layered on shared infrastructure are a sign the fix isn't
+deep enough — prefer generalizing the underlying mechanism over adding special
+cases.
+
+## Phase 2 — Apply the fixes
+
+Dedup findings that point at the same line or mechanism, and fix each remaining
+one directly. Skip any finding whose fix would change intended behavior, require
+changes well outside the reviewed diff, or that you judge to be a false positive
+— note the skip rather than arguing with it. Finish with a brief summary of what
+was fixed and what was skipped (or confirm the code was already clean). State
+clearly in your summary that this was a single-pass review done without the
+`subagent` tool, not the full 4-agent fan-out, so whoever reads it isn't misled
+about what actually ran.

package/src/agent/dispatch.ts

@@ -0,0 +1,353 @@
+/**
+ * src/agent/dispatch.ts — agent dispatch via pi subprocess.
+ *
+ * Reuses the spawn pattern from examples/extensions/subagent and
+ * pi-dynamic-workflows/src/agent/dispatch.ts: one `pi --mode json -p
+ * --no-session` subprocess per agent call, stdout parsed for
+ * {message_end, tool_result_end} events, AbortSignal → SIGTERM with a
+ * 5s SIGKILL escalation.
+ *
+ * This is a SELF-CONTAINED copy (no pi-dynamic-workflows dependency): the
+ * workflow-engine retry/skip/lifecycle machinery is stripped, leaving only
+ * spawnAgent + mapWithConcurrencyLimit + a per-call abort registry. The
+ * subagent tool builds its single/parallel/chain modes on top of this.
+ *
+ * When pi promotes spawnAgent to a public @earendil-works/pi-coding-agent
+ * export, this file should be deleted in favor of that import.
+ */
+import { spawn, type ChildProcess } from "node:child_process";
+import { StringDecoder } from "node:string_decoder";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { Message } from "@earendil-works/pi-ai";
+
+/** Stable id for one agent call; the registry key for per-call abort. */
+export type AgentCallId = string;
+
+/** callId → per-call AbortController. */
+export type AgentAbortMap = Map<AgentCallId, AbortController>;
+
+// ---------------------------------------------------------------------------
+// Concurrency limiter (ported from examples/extensions/subagent)
+// ---------------------------------------------------------------------------
+
+/**
+ * Run `fn` over `items` with at most `concurrency` in flight, preserving
+ * input order in the output array. parallel mode builds on this.
+ */
+export async function mapWithConcurrencyLimit<TIn, TOut>(
+	items: TIn[],
+	concurrency: number,
+	fn: (item: TIn, index: number) => Promise<TOut>,
+): Promise<TOut[]> {
+	if (items.length === 0) return [];
+	const limit = Math.max(1, Math.min(concurrency, items.length));
+	const results: TOut[] = new Array(items.length);
+	let nextIndex = 0;
+	// Stop dispatching NEW items once any worker has errored, so a rejection
+	// doesn't leave sibling workers pulling more items and spawning unawaited
+	// subprocesses. In-flight calls finish; the failing worker rethrows.
+	let failed = false;
+	const workers = new Array(limit).fill(null).map(async () => {
+		while (!failed) {
+			const current = nextIndex++;
+			if (current >= items.length) return;
+			try {
+				results[current] = await fn(items[current], current);
+			} catch (err) {
+				failed = true;
+				throw err;
+			}
+		}
+	});
+	await Promise.all(workers);
+	return results;
+}
+
+// ---------------------------------------------------------------------------
+// pi binary resolution (ported from examples/extensions/subagent)
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the `pi` invocation for the subprocess. Prefers re-entering the
+ * current script (node <script> / bun <script>); falls back to the `pi`
+ * binary on PATH when run under a generic runtime.
+ */
+export function getPiInvocation(args: string[]): { command: string; args: string[] } {
+	const currentScript = process.argv[1];
+	const isBunVirtualScript = currentScript?.startsWith("/$bunfs/root/");
+	if (currentScript && !isBunVirtualScript && fs.existsSync(currentScript)) {
+		return { command: process.execPath, args: [currentScript, ...args] };
+	}
+
+	const execName = path.basename(process.execPath).toLowerCase();
+	const isGenericRuntime = /^(node|bun)(\.exe)?$/.test(execName);
+	if (!isGenericRuntime) {
+		return { command: process.execPath, args };
+	}
+
+	return { command: "pi", args };
+}
+
+// ---------------------------------------------------------------------------
+// Usage + result
+// ---------------------------------------------------------------------------
+
+export interface AgentUsage {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost: number;
+	contextTokens: number;
+	turns: number;
+}
+
+export interface AgentSpawnOptions {
+	/** Stable id for this call; the registry key for per-call abort. */
+	readonly callId: AgentCallId;
+	/** Prompt passed as the final positional arg to `pi -p`. */
+	readonly task: string;
+	/** Working directory for the spawned pi process. Defaults to process.cwd(). */
+	readonly cwd?: string;
+	/** `--model` override. */
+	readonly model?: string;
+	/** `--tools` whitelist (comma-joined). */
+	readonly tools?: string[];
+	/** System prompt appended via a temp file (`--append-system-prompt`). */
+	readonly systemPrompt?: string;
+	/** Caller-level abort signal; linked to this call's per-call controller. */
+	readonly signal?: AbortSignal;
+	/** Max assistant turns. When reached, the subprocess is aborted (SIGTERM). Omit for unlimited. */
+	readonly maxTurns?: number;
+}
+
+export interface AgentSpawnResult {
+	callId: AgentCallId;
+	exitCode: number;
+	messages: Message[];
+	stderr: string;
+	usage: AgentUsage;
+	model?: string;
+	stopReason?: string;
+	errorMessage?: string;
+	/** True if aborted. exitCode may be null/non-zero. */
+	aborted: boolean;
+	/** True if killed because the caller's maxTurns budget was reached. Distinct
+	 *  from `aborted` (external cancel): the agent did useful bounded work. */
+	maxTurnsReached: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Registry — Map<callId, ChildProcess> + per-call AbortController
+// ---------------------------------------------------------------------------
+
+export interface AgentSpawnRegistry {
+	/** callId → child process. The table that translates abort → SIGTERM on one process. */
+	readonly processes: Map<AgentCallId, ChildProcess>;
+	/** callId → per-call controller. */
+	readonly controllers: AgentAbortMap;
+}
+
+export function createSpawnRegistry(): AgentSpawnRegistry {
+	return {
+		processes: new Map(),
+		controllers: new Map(),
+	};
+}
+
+/**
+ * Abort exactly one in-flight call by id. Aborts the call's per-call
+ * controller; spawnAgent's race-safe listener translates that into
+ * SIGTERM→SIGKILL on exactly the one subprocess. Returns false if the
+ * callId is not in flight.
+ */
+export function abortAgent(registry: AgentSpawnRegistry, callId: AgentCallId): boolean {
+	const controller = registry.controllers.get(callId);
+	if (!controller) return false;
+	controller.abort();
+	return true;
+}
+
+// ---------------------------------------------------------------------------
+// Spawn — the dispatch primitive
+// ---------------------------------------------------------------------------
+
+export async function spawnAgent(
+	registry: AgentSpawnRegistry,
+	options: AgentSpawnOptions,
+): Promise<AgentSpawnResult> {
+	const { callId, task, cwd, model, tools, systemPrompt, signal } = options;
+
+	// Per-call controller — the abort entry point.
+	const controller = new AbortController();
+	registry.controllers.set(callId, controller);
+
+	// Link the caller-level signal to this call's controller so a run-wide
+	// abort reaches every in-flight call. Named + removed in finally — otherwise
+	// a normally-completing call leaks a listener on the parent signal.
+	const onParentAbort = (): void => controller.abort();
+	if (signal) {
+		if (signal.aborted) controller.abort();
+		else signal.addEventListener("abort", onParentAbort);
+	}
+
+	const args: string[] = ["--mode", "json", "-p", "--no-session"];
+	if (model) args.push("--model", model);
+	if (tools && tools.length > 0) args.push("--tools", tools.join(","));
+
+	let tmpPromptDir: string | null = null;
+	let tmpPromptPath: string | null = null;
+
+	const result: AgentSpawnResult = {
+		callId,
+		exitCode: 0,
+		messages: [],
+		stderr: "",
+		usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+		aborted: false,
+		maxTurnsReached: false,
+	};
+
+	try {
+		if (systemPrompt && systemPrompt.trim()) {
+			const tmp = await writePromptToTempFile(callId, systemPrompt);
+			tmpPromptDir = tmp.dir;
+			tmpPromptPath = tmp.filePath;
+			args.push("--append-system-prompt", tmpPromptPath);
+		}
+
+		// The prompt is the final positional arg consumed by `-p`.
+		args.push(task);
+
+		const exitCode = await new Promise<number>((resolve) => {
+			const invocation = getPiInvocation(args);
+			const proc = spawn(invocation.command, invocation.args, {
+				cwd: cwd ?? process.cwd(),
+				shell: false,
+				stdio: ["ignore", "pipe", "pipe"],
+			});
+			registry.processes.set(callId, proc);
+
+			let buffer = "";
+			const decoder = new StringDecoder("utf8");
+
+			const processLine = (line: string) => {
+				if (!line.trim()) return;
+				let event: { type: string; message?: Message };
+				try {
+					event = JSON.parse(line) as { type: string; message?: Message };
+				} catch {
+					return;
+				}
+
+				if (event.type === "message_end" && event.message) {
+					const msg = event.message;
+					result.messages.push(msg);
+					if (msg.role === "assistant") {
+						result.usage.turns++;
+						// Enforce maxTurns: abort the subprocess when the limit is reached.
+						// killProc handles the SIGTERM→SIGKILL escalation. Use `!= null` so an
+						// explicit maxTurns: 0 is honored (and marked) rather than treated as "unset".
+						if (options.maxTurns != null && result.usage.turns >= options.maxTurns) {
+							result.maxTurnsReached = true;
+							controller.abort();
+						}
+						const usage = msg.usage;
+						if (usage) {
+							result.usage.input += usage.input || 0;
+							result.usage.output += usage.output || 0;
+							result.usage.cacheRead += usage.cacheRead || 0;
+							result.usage.cacheWrite += usage.cacheWrite || 0;
+							result.usage.cost += Number(usage.cost?.total) || 0;
+							result.usage.contextTokens = usage.totalTokens || 0;
+						}
+						if (!result.model && msg.model) result.model = msg.model;
+						if (msg.stopReason) result.stopReason = msg.stopReason;
+						if (msg.errorMessage) result.errorMessage = msg.errorMessage;
+					}
+				}
+
+				if (event.type === "tool_result_end" && event.message) {
+					result.messages.push(event.message);
+				}
+			};
+
+			proc.stdout.on("data", (data) => {
+				// StringDecoder buffers incomplete multi-byte UTF-8 sequences across chunk
+				// boundaries so a CJK char split between two `data` events isn't replaced
+				// with U+FFFD (which would corrupt the line and silently drop the event).
+				buffer += decoder.write(data);
+				const lines = buffer.split("\n");
+				buffer = lines.pop() || "";
+				for (const line of lines) processLine(line);
+			});
+
+			proc.stderr.on("data", (data) => {
+				result.stderr += data.toString();
+			});
+
+			proc.on("close", (code) => {
+				const tail = decoder.end();
+				if (tail) buffer += tail;
+				if (buffer.trim()) processLine(buffer);
+				resolve(code ?? 1); // code===null → signal-killed (OOM/SIGKILL): treat as failure, not silent empty success
+			});
+
+			proc.on("error", (err) => {
+				// Surface the spawn error (e.g. ENOENT when `pi` is not on PATH) instead
+				// of swallowing it.
+				result.errorMessage = err.message;
+				result.stderr += err.message;
+				resolve(1);
+			});
+
+			// Per-call abort → SIGTERM (SIGKILL after 5s). Race-safe: if the controller
+			// was already aborted before this listener registered, kill now.
+			const killProc = () => {
+				// Late-abort guard: if the proc already exited, don't flip a successful
+				// result's `aborted` flag.
+				if (proc.exitCode !== null || proc.signalCode !== null) return;
+				result.aborted = true;
+				proc.kill("SIGTERM");
+				const timer = setTimeout(() => {
+					// SIGTERM may be ignored — force SIGKILL after the grace period.
+					proc.kill("SIGKILL");
+				}, 5000);
+				// Clear the timer once the proc exits so we don't leak a libuv handle.
+				proc.once("close", () => clearTimeout(timer));
+			};
+			if (controller.signal.aborted) killProc();
+			else controller.signal.addEventListener("abort", killProc, { once: true });
+		});
+
+		result.exitCode = exitCode;
+		return result;
+	} finally {
+		// Always release registry slots, the parent-signal listener, and temp files.
+		registry.processes.delete(callId);
+		registry.controllers.delete(callId);
+		if (signal) signal.removeEventListener("abort", onParentAbort);
+		if (tmpPromptPath)
+			try {
+				fs.unlinkSync(tmpPromptPath);
+			} catch {
+				/* ignore */
+			}
+		if (tmpPromptDir)
+			try {
+				fs.rmdirSync(tmpPromptDir);
+			} catch {
+				/* ignore */
+			}
+	}
+}
+
+async function writePromptToTempFile(callId: string, prompt: string): Promise<{ dir: string; filePath: string }> {
+	const tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "pi-cr-agent-"));
+	const safeName = callId.replace(/[^\w.-]+/g, "_");
+	const filePath = path.join(tmpDir, `prompt-${safeName}.md`);
+	await fs.promises.writeFile(filePath, prompt, { encoding: "utf-8", mode: 0o600 });
+	return { dir: tmpDir, filePath };
+}

package/src/commands/code-review.ts

@@ -0,0 +1,100 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { bundledSkillPath } from "../skills.ts";
+
+/** Effort levels the /code-review command accepts (mirrors CC's effort enum). */
+export const REVIEW_LEVELS = ["low", "medium", "high", "xhigh", "max"] as const;
+export type ReviewLevel = (typeof REVIEW_LEVELS)[number];
+
+const DEFAULT_LEVEL: ReviewLevel = "low";
+
+/** Where the last explicitly-typed effort is persisted (CC 2.1.223 codeReviewLastEffort). */
+const STATE_FILE = path.join(os.homedir(), ".pi", ".pi-review-state.json");
+
+export type EffortSource = "explicit" | "last-used" | "default";
+
+/**
+ * Parse a leading effort level out of raw args; the remainder (flags + target)
+ * is returned verbatim. Pure — unit-testable. Mirrors CC's ecl()/Tjn(): the
+ * first token is the level only if it matches the enum; otherwise the whole
+ * string is the target/flags.
+ */
+export function parseReviewArgs(args: string): { level: ReviewLevel | undefined; rest: string } {
+	const tokens = (args ?? "").trim().split(/\s+/).filter(Boolean);
+	if (tokens.length === 0) return { level: undefined, rest: "" };
+	const first = tokens[0]!.toLowerCase();
+	const isLevel = (REVIEW_LEVELS as readonly string[]).includes(first);
+	return {
+		level: isLevel ? (first as ReviewLevel) : undefined,
+		rest: isLevel ? tokens.slice(1).join(" ") : tokens.join(" "),
+	};
+}
+
+/**
+ * Resolve the effective effort + where it came from. Pure — unit-testable.
+ * Mirrors CC 2.1.223: explicit wins; otherwise reuse the last-typed level;
+ * otherwise the default. (220 defaulted straight to low with no memory.)
+ */
+export function resolveEffort(
+	explicit: ReviewLevel | undefined,
+	lastUsed: ReviewLevel | undefined,
+): { level: ReviewLevel; source: EffortSource } {
+	if (explicit) return { level: explicit, source: "explicit" };
+	if (lastUsed) return { level: lastUsed, source: "last-used" };
+	return { level: DEFAULT_LEVEL, source: "default" };
+}
+
+// Best-effort persistence — sticky-effort is a convenience, not a correctness
+// invariant; a read/write failure must not break the review.
+function readLastEffort(): ReviewLevel | undefined {
+	try {
+		const raw = JSON.parse(fs.readFileSync(STATE_FILE, "utf8")) as { codeReviewLastEffort?: unknown };
+		const v = raw.codeReviewLastEffort;
+		return typeof v === "string" && (REVIEW_LEVELS as readonly string[]).includes(v)
+			? (v as ReviewLevel)
+			: undefined;
+	} catch {
+		return undefined;
+	}
+}
+function writeLastEffort(level: ReviewLevel): void {
+	try {
+		fs.mkdirSync(path.dirname(STATE_FILE), { recursive: true });
+		fs.writeFileSync(STATE_FILE, JSON.stringify({ codeReviewLastEffort: level }));
+	} catch {
+		/* ignore — non-critical */
+	}
+}
+
+/**
+ * Register the /code-review command — triggers the code-review skill.
+ *
+ * Handler decides the effective effort deterministically (CC 2.1.223): an
+ * explicit level is persisted and used; with no level, the last-typed level is
+ * reused; with no history, it falls back to low. The decision is announced in
+ * the trigger message so it is observable — same pattern as /code-simplify.
+ */
+export function registerCodeReview(pi: ExtensionAPI): void {
+	pi.registerCommand("code-review", {
+		description:
+			"Review the current diff using the code-review skill. Usage: /code-review [low|medium|high|xhigh|max] [--fix] [--comment] [--share] [<pr#>|<branch>|<path>]",
+		getArgumentCompletions(prefix) {
+			const tokens = ["low", "medium", "high", "xhigh", "max", "--fix", "--comment", "--share"];
+			return tokens.filter((t) => t.startsWith(prefix)).map((t) => ({ label: t, value: t }));
+		},
+		async handler(args) {
+			const { level: explicit, rest } = parseReviewArgs(args ?? "");
+			// Skip the read when we just wrote it — resolveEffort returns `explicit` unchanged.
+			const lastUsed = explicit ? undefined : readLastEffort();
+			if (explicit) writeLastEffort(explicit); // CC 2.1.223: remember the explicit level
+			const { level, source } = resolveEffort(explicit, lastUsed);
+			pi.sendUserMessage(
+				`Run a code review now. Effective effort: ${level} (${source})${rest ? `; extra args: ${rest}` : ""}.\n\n` +
+					`First load the review skill with the read tool: ${bundledSkillPath("code-review/SKILL.md")}. ` +
+					`Then follow it exactly — use the \`subagent\` tool for any fan-out / verify / gap-hunt the skill calls for.`,
+			);
+		},
+	});
+}

package/src/commands/code-simplify.ts

@@ -0,0 +1,66 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { bundledSkillPath } from "../skills.ts";
+
+/** Context fraction at which we fall back to single-pass — a Pi-specific heuristic (see decideSimplifyMode). */
+const CONTEXT_NEAR_FULL_THRESHOLD = 0.8;
+
+export type SimplifyMode = "parallel" | "single-pass";
+
+/**
+ * Decide simplify mode deterministically from real context usage + tool availability.
+ * Pure function — unit-testable.
+ *
+ * CC parity note: CC's /simplify guard (_Yo) is a SPAWN-DEPTH recursion limit, NOT a
+ * context check — `RO(ctx) >= dne()` where RO returns the agent's depth and dne()
+ * returns CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH (default 3). That is N/A on Pi: the
+ * `subagent` tool spawns a fresh subprocess (depth 0), so depth never accumulates.
+ * The context-fraction heuristic below is a Pi-specific substitute (don't fan out
+ * when the parent's context is near-full), NOT a mirror of _Yo. The other _Yo clause
+ * — the Agent tool must be in the allowlist — IS mirrored here as `hasSubagent`.
+ */
+export function decideSimplifyMode(opts: {
+	tokens: number | null;
+	contextWindow: number;
+	hasSubagent: boolean;
+}): SimplifyMode {
+	const { tokens, contextWindow, hasSubagent } = opts;
+	// Conservative: if we can't measure context (tokens unknown / window 0) or the
+	// subagent tool isn't registered, don't risk fan-out — go single-pass.
+	if (tokens == null || contextWindow <= 0 || !hasSubagent) return "single-pass";
+	const nearFull = tokens / contextWindow >= CONTEXT_NEAR_FULL_THRESHOLD;
+	return nearFull ? "single-pass" : "parallel";
+}
+
+/**
+ * Register the /code-simplify command. The handler decides parallel vs single-pass from
+ * ctx.getContextUsage() (real token count) + subagent tool availability — this is the
+ * deterministic Jvo guard that a pure-prompt skill cannot reproduce.
+ */
+export function registerSimplify(pi: ExtensionAPI): void {
+	pi.registerCommand("code-simplify", {
+		description:
+			"Clean up the changed code (reuse/simplification/efficiency/altitude) using the simplify skill. Mode (parallel 4-agent vs single-pass) is decided by the handler from real context usage. Usage: /code-simplify [<target>]",
+		async handler(args, ctx) {
+			const usage = ctx.getContextUsage();
+			const hasSubagent = pi.getAllTools().some((t) => t.name === "subagent");
+			const mode = decideSimplifyMode({
+				tokens: usage?.tokens ?? null,
+				contextWindow: usage?.contextWindow ?? 0,
+				hasSubagent,
+			});
+			const pct =
+				usage && usage.tokens != null && usage.contextWindow > 0
+					? Math.round((usage.tokens / usage.contextWindow) * 100) + "%"
+					: "?";
+			const bodyLabel = mode === "parallel" ? "PARALLEL MODE" : "SINGLE-PASS MODE";
+			pi.sendUserMessage(
+				`Clean up the changed code now. Target: ${args || "(whole diff)"}.\n\n` +
+					`Handler decided ${mode} mode (context ${pct} full, subagent ${hasSubagent ? "available" : "absent"}). ` +
+					`Load ${bundledSkillPath("simplify/SKILL.md")} via the read tool and follow the ${bodyLabel} body. ` +
+					(mode === "parallel"
+						? `Use the \`subagent\` tool (mode: parallel) for the 4-agent fan-out.`
+						: `Work the four angles inline — do not fake fan-out.`),
+			);
+		},
+	});
+}