one-code-extension 0.1.3 → 0.3.0

package/docs/decisions.md

@@ -1,148 +0,0 @@
-# Decisions
-
-Why this package is shaped the way it is — the choices that aren't obvious from
-the code, and which community packages were adopted, rejected, or replaced and
-on what evidence. This file is the **index**: a one-liner per decision, grouped
-by area. Full rationale lives in `docs/decisions/`; follow the link on each
-entry. (Companion docs: [`findings.md`](findings.md) for how pi behaves,
-[`handoff.md`](handoff.md) for current state and what's left.)
-
-## Distribution & dependencies
-
-Full context: [`decisions/distribution.md`](decisions/distribution.md).
-
-- **[Two artifacts from one codebase: the app and the package](decisions/distribution.md#two-artifacts-from-one-codebase-the-app-and-the-package-2026-08-10)** — npm `@one-ai/one-code` (bundled app: pinned pi, `~/.one-code` isolation via `PI_CODING_AGENT_DIR`, package-registration load shape, stdout rebranding, own update check) + npm `one-code-extension` (peer-dep pi package with a runtime tested-range warning); lockstep versions from 0.1.2; Homebrew tap `isurumaduranga/one-ai` delivers the app (brew's `--min-release-age=1` makes day-one brew installs fail by design).
-- **[Distribution: pi package, not a wrapper binary](decisions/distribution.md#distribution-pi-package-not-a-wrapper-binary)** — *(partially superseded by the two-artifact model)* ship as an installable pi package because pi's rebranding resolves from pi's own `package.json`; a dependent can't rebrand it, and a package keeps upstream upgrades a version bump away.
-- **[Community packages: adopted where they work](decisions/distribution.md#community-packages-adopted-where-they-work)** — prefer ecosystem packages, but trial first: only `pi-ask-user` survived; `pi-subagents` was rejected (children SIGKILLed ~29 ms after spawn here).
-- **[Publish readiness (Phase 7)](decisions/distribution.md#publish-readiness-phase-7)** — what's done and what remains before `npm publish` (metadata, tarball, install-path verification).
-
-## Branding, themes & startup
-
-Full context: [`decisions/branding.md`](decisions/branding.md).
-
-- **[Branding without a fork](decisions/branding.md#branding-without-a-fork)** — the π banner, shortcut hints, and resource sections are extension output, not a patched pi; `CC_NO_BANNER=1` restores pi's header.
-- **[Themes: authored, not adopted](decisions/branding.md#themes-authored-not-adopted)** — `one-code`/`one-code-light` are hand-authored 51-token themes; no community theme fit.
-- **[Rebrand: pincer](decisions/branding.md#rebrand-pincer)** — (history) why the product was "pincer" / npm `pincer-agent`, and Claude Code stays descriptive ("compatible with…") never titular.
-- **[Rebrand: One Code](decisions/branding.md#rebrand-one-code)** — pincer → **One Code** / npm `one-code`: the stacked wordmark, the full rename surface (state dir, env, channels, repo), and what stays as history.
-- **[Startup listing: quietStartup + banner sections](decisions/branding.md#startup-listing-quietstartup-banner-sections)** — when pi's `quietStartup` is on, compact context/skills/workflows/themes sections replace pi's noisy resource listing.
-
-## System prompt
-
-Full context: [`decisions/system-prompt.md`](decisions/system-prompt.md).
-
-- **[Per-turn `before_agent_start`, not a static override](decisions/system-prompt.md#system-prompt-per-turn-before_agent_start-not-a-static-override)** — rebuilt each turn so it reflects the live tool set (plan mode, deferred loading change it); the environment block is cached per (cwd, model) to stay byte-stable for prompt caching.
-- **[Tiered by model capability](decisions/system-prompt.md#system-prompt-tiered-by-model-capability-2026-08-07)** — three prompt tiers selected by model capability, tuning prompt *text* only (decoding params are a separate future dial).
-
-## Tools
-
-Full context: [`decisions/tools.md`](decisions/tools.md).
-
-- **[Tool names stay pi-idiomatic (snake_case)](decisions/tools.md#tool-names-stay-pi-idiomatic-snake_case)** — register `todo_write`/`subagent`-style names; `matcher.ts` maps users' Claude Code PascalCase permission rules onto them.
-- **[Deferred tools (ToolSearch)](decisions/tools.md#deferred-tools-toolsearch)** — how tool schemas are kept out of the prompt until asked for, using the provider's native mechanism where available.
-- **[Web tools](decisions/tools.md#web-tools)** — `web_search` wraps the one community dep (`pi-web-search`); the rest is our own.
-- **[AskUserQuestion — our own](decisions/tools.md#askuserquestion-our-own)** — the multi-question schema, option lists, multi-select, and headless fallback.
-- **[web_fetch answers a `prompt` with a reader model](decisions/tools.md#web_fetch-answers-a-prompt-with-a-reader-model)** — fetch → readability → markdown, and an optional `prompt` answered by a small reader model with a loud raw-content fallback.
-- **[Tool errors fail loud, never soft-fallback](decisions/tools.md#tool-errors-fail-loud-never-soft-fallback)** — a malformed/ambiguous call returns `isError:true` with the fix named, never a plausible-but-wrong success (the `subagent`-catalog archetype); audit + the 13 fixes across 12 tools.
-- **[Harness discipline (divergences found by self-comparison)](decisions/tools.md#harness-discipline-divergences-found-by-self-comparison)** — Claude-Code-compatible behaviours found by self-comparison that aren't obvious from any single tool.
-- **[Tier-aware tool surface: search built-ins for mid/low only (unreviewed)](decisions/tools.md#tier-aware-tool-surface-search-built-ins-for-midlow-only-unreviewed)** — pi never activates `grep`/`find`/`ls`; mid/low tiers now get them (their prompts demand them), frontier stays lean like Claude Code's.
-- **[Subagent steering: injected catalog, fork hardening (unreviewed)](decisions/tools.md#subagent-steering-injected-catalog-fork-hardening-unreviewed)** — the agent catalog rides an every-turn reminder; a fork's task gets a do-only-this preamble; `model`/`thinking` on a fork fail loud.
-- **[Background bash: override the built-in, gate before detaching (unreviewed)](decisions/tools.md#background-bash-override-the-built-in-gate-before-detaching-unreviewed)** — `run_in_background` on a pi-executor-delegating `bash` override; task_output/task_stop work unchanged; never auto-allowed.
-- **[Deferral runs on all tiers; steering follows CC's channels](decisions/tools.md#deferral-runs-on-all-tiers-steering-follows-ccs-channels-2026-08-10)** — deferral applies on every tier (capture-confirmed CC defers on Haiku too; verified 35→15 tools on deepseek); notifications carry CC's anti-confabulation preamble; MCP server `instructions` are injected, not dropped.
-- **[CLAUDE.md, memory, and skills injected as the CC reminder stack](decisions/tools.md#claudemd-memory-and-skills-injected-as-the-cc-reminder-stack-2026-08-10)** — moved out of the system prompt into the byte-identical first-user-message `<system-reminder>` stack (`claude-context` + `lib/claude-context.ts`, placement/order/suffix on the reminder queue).
-
-## Auto mode
-
-Full context: [`decisions/auto-mode.md`](decisions/auto-mode.md).
-
-- **[A deterministic pre-gate in front of an LLM classifier](decisions/auto-mode.md#auto-mode-a-deterministic-pre-gate-in-front-of-an-llm-classifier)** — a shell pre-gate that may only ever conclude "safe" (a latency optimisation, never a deny path), backed by an LLM approval classifier.
-- **[Parity pass against published Claude Code behaviour](decisions/auto-mode.md#auto-mode-parity-pass-against-the-published-claude-code-behaviour)** — where our auto mode was aligned to the shipped Claude Code auto-approve behaviour.
-- **[Grounding the verdict: cite a rule, don't narrate one](decisions/auto-mode.md#grounding-the-classifiers-verdict-cite-a-rule-dont-narrate-one)** — nothing the classifier says is trusted unless checked: a block must cite a real rule id, the tier comes from that id, an intent-based allow must quote the user verbatim.
-- **[Choosing the classifier model without leaking the session](decisions/auto-mode.md#choosing-the-classifier-model-without-leaking-the-session-to-another-provider)** — the classifier never silently changes provider; models are picked by cost + a per-provider default table, not id substrings.
-- **[Three defects the real OpenRouter catalog exposed](decisions/auto-mode.md#three-defects-the-real-openrouter-catalog-exposed)** — what a live gateway catalog broke in model selection, and the fixes.
-- **[Prompt caching, input size, and vendor containment on gateways](decisions/auto-mode.md#prompt-caching-input-size-and-vendor-containment-on-gateways)** — the stable prefix lives in the system prompt to cache; untrusted CLAUDE.md stays in the user message; sizing for Haiku's 4096-token prefix.
-- **[Hardening: the pi-automode review, and what came of it](decisions/auto-mode.md#auto-mode-hardening-the-pi-automode-review-and-what-came-of-it)** — the fail-closed posture: candidate chain, released pin on mid-session model death, deterministic floor for writes to the gate's own config.
-
-## Code review
-
-Full context: [`decisions/code-review-remediation.md`](decisions/code-review-remediation.md).
-
-- **[Auto-mode gate hardening: four false "safe" verdicts closed](decisions/code-review-remediation.md#auto-mode-gate-hardening-four-false-safe-verdicts-closed-2026-08-10)** — bare redirects, read-only-command redirects, `git -C <outside>`, `sort -o`, and `Bash(sh -c *)` rules all reached "safe"/allow without their real effect being weighed; every fix converts a false "safe" into an escalation, keeping the pre-gate's never-deny contract.
-- **[Worktree vs. permission rules — preserve-original, not reorder](decisions/code-review-remediation.md#worktree-vs-permission-rules--preserve-original-not-reorder-2026-08-10)** — worktree's `cd`-wrapper defeated every Bash rule; the original command is preserved for rule-matching while the classifier keeps seeing the wrapped command. Reordering permissions ahead of worktree was rejected (it would move containment to the wrong dir).
-- **[Background subagents now get the holistic review](decisions/code-review-remediation.md#background-subagents-now-get-the-holistic-review-2026-08-10)** — the end-of-run "review the whole action sequence" checkpoint now fires for background/resident runs, delivered as a follow-up since there is no `tool_result` to attach to.
-
-## Modes & keybindings
-
-Full context: [`decisions/modes.md`](decisions/modes.md).
-
-- **[`/effort`, and ultracode as a standing mode](decisions/modes.md#effort-and-ultracode-as-a-standing-mode)** — one "effort" dial; its last stop is `ultracode` = xhigh plus workflows armed every turn.
-- **[Aligning `/effort` with shift+tab](decisions/modes.md#aligning-effort-with-shifttab)** — why the slider mirrors shift+tab's model-filtered stops and dims the rest (pi reserves that key).
-- **[Permission-mode cycling on ctrl+q](decisions/modes.md#permission-mode-cycling-on-ctrlq-not-shifttab-ctrlm-or-altm)** — why the mode cycle is ctrl+q, not shift+tab / ctrl+m / alt+m.
-- **[Plan mode is file-based, like current Claude Code](decisions/modes.md#plan-mode-is-file-based-like-current-claude-code)** — plan mode writes a plan file under `~/.one-code/plans`; the matcher allows writes to that one file.
-
-## Subagents & workflows
-
-Full context: [`decisions/subagents-workflows.md`](decisions/subagents-workflows.md).
-
-- **[Subagents: what matches Claude Code and what does not](decisions/subagents-workflows.md#subagents-what-matches-claude-code-and-what-does-not)** — the parity map for the subagent tool (fork, worktree isolation, background runs, two-way messaging).
-- **[Permission modes and subagents](decisions/subagents-workflows.md#permission-modes-and-subagents)** — how permission mode propagates into subagent sessions.
-- **[Subagent model selection, resolved in the parent](decisions/subagents-workflows.md#subagent-model-selection-resolved-in-the-parent-advertised-by-reminder)** — aliases stay in-provider, crossings are announced, defaults come from `CLAUDE_CODE_SUBAGENT_MODEL`/`subagentModel`, menu re-advertised every turn.
-- **[Workflow tool (ultracode orchestration)](decisions/subagents-workflows.md#workflow-tool-ultracode-orchestration)** — vm-sandboxed JS scripts fanning out to in-process subagents; background runs, journal resume, saved workflows.
-
-## Model policy
-
-Full context: [`decisions/model-policy.md`](decisions/model-policy.md).
-
-- **[Shared role profiles](decisions/model-policy.md#shared-role-profiles-smaller-classifiers-and-delegated-workers-by-default)** — one same-provider/family table gives classifiers, delegated workers, and reader models a smaller default.
-- **[Upward cost pressure](decisions/model-policy.md#upward-cost-pressure-an-informational-warning-and-a-per-call-gate)** — an informational warning plus a per-call gate when a delegated model costs more than the session's.
-
-## Memory & session state
-
-Full context: [`decisions/memory-state.md`](decisions/memory-state.md).
-
-- **[Memory: own file-based implementation](decisions/memory-state.md#memory-own-file-based-implementation)** — Claude Code's `~/.claude/projects/<slug>/memory/` layout keyed by git root; relevance-based mid-session recall is unreplicable client internals.
-- **[The memory dir is harness-designated working space](decisions/memory-state.md#the-memory-dir-is-harness-designated-working-space-like-the-plan-file)** — why writes there need no permission prompt, like the plan file.
-- **[Session scratchpad, Claude Code-style](decisions/memory-state.md#session-scratchpad-claude-code-style)** — a per-session temp dir: prompt section plus the allowed-writes rule.
-- **[Own state, borrowed config](decisions/memory-state.md#own-state-borrowed-config-claude-is-read-only-one-code-writes-to-one-code)** — `.claude` is read-only; One Code writes its own state to `~/.one-code` so the two never clobber each other.
-
-## Compaction
-
-Full context: [`decisions/compaction.md`](decisions/compaction.md).
-
-- **[Compaction runs Claude Code's prompt, via session_before_compact](decisions/compaction.md#compaction-runs-claude-codes-prompt-via-session_before_compact)** — Claude Code's compaction prompt, `<summary>` extraction, an economical model, and the `CC_COMPACTION=0` pi fallback.
-- **[The cache miss, and the two-part fix](decisions/compaction.md#the-cache-miss-and-the-two-part-fix-2026-08-07)** — why the compaction call missed the prompt cache and the capture-based replay + reasoning-mirror + Anthropic beta-replay that fixed it, live-verified on three providers.
-
-## MCP
-
-Full context: [`decisions/mcp.md`](decisions/mcp.md).
-
-- **[MCP — our own client on the official SDK](decisions/mcp.md#mcp-our-own-client-on-the-official-sdk)** — `.mcp.json` discovery, `mcp__server__tool` naming, resources.
-- **[MCP servers with unset credentials](decisions/mcp.md#mcp-servers-with-unset-credentials)** — how a server with missing credentials is handled rather than crashing discovery.
-- **[Background connect: session_start no longer blocks the prompt](decisions/mcp.md#background-connect-session_start-no-longer-blocks-the-prompt-2026-08-10)** — the awaited MCP handshake *was* the 4.9s startup (findings §15); now fire-and-forget in the interactive session (501ms measured), still awaited in one-shots and subagent children; SDK import lazified.
-
-## LSP
-
-Full context: [`decisions/lsp.md`](decisions/lsp.md).
-
-- **[LSP: our own client, not a package](decisions/lsp.md#lsp-our-own-client-not-a-package)** — a zero-dep LSP client for post-edit diagnostics and `lsp_diagnostics`.
-
-## Skills & plugins
-
-Full context: [`decisions/skills-plugins.md`](decisions/skills-plugins.md).
-
-- **[Skills and plugins](decisions/skills-plugins.md#skills-and-plugins)** — `~/.claude` + `.claude` skills/commands discovery, and Claude Code plugins contributing namespaced agents/skills/commands/MCP.
-
-## TUI
-
-Full context: [`decisions/tui.md`](decisions/tui.md).
-
-- **[Compact tool rendering — the Claude Code transcript look](decisions/tui.md#compact-tool-rendering-the-claude-code-transcript-look-unreviewed)** *(unreviewed)* — `●`/`⎿` call+result lines with ctrl+o collapse for every One Code tool, compact `✳` notification headlines, boxless theme, dimmer thinking text.
-- **[Thinking collapsed by default, expandable with ctrl+t](decisions/tui.md#thinking-collapsed-by-default-expandable-with-ctrlt-unreviewed)** *(unreviewed)* — pi's own `hideThinkingBlock` defaulted on (only when the user never chose), `✻ Thinking…` label via `setHiddenThinkingLabel`; the write lands next session (settings cached at startup).
-- **[Built-in tools joined the ● language; banner cut to four lines](decisions/tui.md#built-in-tools-joined-the--language-banner-cut-to-four-lines-unreviewed)** *(unreviewed)* — `tool-style` wraps pi's read/write/edit/grep/find/ls renderers (`● Label(arg)` + base result under a `⎿` elbow, edit's diff preview kept); one curated hint line, sections as counts, warnings point at /lsp & /mcp.
-- **[Fullscreen (alt-screen) for Claude Code's clean exit — a setting, not extension code](decisions/tui.md#fullscreen-alt-screen-for-claude-codes-clean-exit-a-setting-not-extension-code-unreviewed)** *(unreviewed)* — CC's clean exit is the terminal alt-screen buffer; pi has it as `tuiMode: "fullscreen"`, but the renderer is a pi-core startup choice with no extension hook, so One Code recommends the setting rather than owning it.
-- **[Render memoization: components cache by width](decisions/tui.md#render-memoization-components-cache-by-width-2026-08-10)** — pi-tui renders every mounted component every frame (findings §15), so `linesComponent` memoizes by width (safe: state changes mint fresh components; `invalidate()` clears); `truncateLine` got a raw-length fast path. Rule: every custom renderer component must memoize `render(width)`.
-
-## Hooks
-
-Full context: [`decisions/hooks.md`](decisions/hooks.md).
-
-- **[Hooks: own the mechanism, port the best of three references](decisions/hooks.md#hooks-own-the-mechanism-port-the-best-of-three-references)** — 8 events, the Claude Code stdin/envelope protocol, ask→block fail-closed, once-per-config consent, and running before worktree/permissions.

package/extensions/subagents/child.ts

@@ -1,414 +0,0 @@
-/**
- * Child-process subagent runner: spawns `pi --mode json -p`, parses its JSONL
- * event stream, and exposes a handle usable both foreground (await result)
- * and background (kill/snapshot, registered as a background task).
- *
- * Children persist their sessions (`--session-dir` per run) so a finished
- * agent can be resumed later via `--session <file>` — that is what
- * send_message builds on. `--no-session` is only the fallback when the parent
- * itself has no session directory.
- */
-
-import { spawn } from "node:child_process";
-import { existsSync, mkdtempSync, writeFileSync } from "node:fs";
-import os from "node:os";
-import { basename, join } from "node:path";
-import { type ChildAction, recordAction } from "../auto-mode/actions.ts";
-import type { AgentDefinition } from "./agents.ts";
-import { RpcTurnTracker, toMainMessage } from "./rpc-turns.ts";
-import { addUsage, emptyUsage, type UsageTotals } from "./usage.ts";
-
-export const OUTPUT_CAP = 50_000;
-
-export function piInvocation(args: string[]): { command: string; args: string[] } {
-	const currentScript = process.argv[1];
-	if (currentScript && !currentScript.startsWith("/$bunfs/root/") && existsSync(currentScript)) {
-		return { command: process.execPath, args: [currentScript, ...args] };
-	}
-	const execName = basename(process.execPath).toLowerCase();
-	if (!/^(node|bun)(\.exe)?$/.test(execName)) {
-		return { command: process.execPath, args };
-	}
-	return { command: "pi", args };
-}
-
-/**
- * Framing wrapped around a fork child's task. A fork inherits the parent's
- * entire transcript; without this, a weaker model tends to abandon its
- * assigned task and continue (or confabulate about) the inherited topic —
- * then its output returns to the parent looking like independent
- * confirmation. See docs/handoff-tool-ambiguity.md (fork confabulation).
- */
-export function forkTaskMessage(task: string): string {
-	return [
-		"You are a forked subagent. The conversation above is inherited context, for reference only — do NOT continue its open threads, verify its claims, or act on its plans. Do ONLY the task below; your final message is returned to the parent conversation verbatim, as data. You cannot see the parent's background tasks: its task ids are not addressable from here.",
-		"",
-		"Task:",
-		task,
-	].join("\n");
-}
-
-export interface ChildOptions {
-	agent?: AgentDefinition;
-	task: string;
-	cwd: string;
-	/** Parent session file, for fork runs. */
-	forkFrom?: string;
-	/** Existing child session to continue (send_message). */
-	sessionFile?: string;
-	/** Where a new run's session file lands; falls back to --no-session. */
-	sessionDir?: string;
-	model?: string;
-	thinking?: string;
-	signal?: AbortSignal;
-	onProgress: (toolCalls: number, lastText: string, usage: UsageTotals) => void;
-	/** The child called send_message {to: "main"} — relay it to the main conversation. */
-	onMessageToMain?: (message: string, summary?: string) => void;
-}
-
-/** Session/agent/model flags shared by print and rpc children. */
-function buildChildFlags(options: Omit<ChildOptions, "task" | "signal" | "onProgress">): string[] {
-	const { agent, forkFrom, sessionFile, sessionDir } = options;
-	const args: string[] = [];
-
-	if (sessionFile) {
-		args.push("--session", sessionFile);
-	} else if (forkFrom) {
-		// pi forks the session file into a fresh session, so the child starts with
-		// the parent's transcript and our own system prompt still applies.
-		args.push("--fork", forkFrom);
-		if (sessionDir) args.push("--session-dir", sessionDir);
-	} else {
-		if (sessionDir) args.push("--session-dir", sessionDir);
-		else args.push("--no-session");
-		if (agent) {
-			const tmpDir = mkdtempSync(join(os.tmpdir(), "cc-subagent-"));
-			const promptPath = join(tmpDir, "system.md");
-			writeFileSync(promptPath, agent.systemPrompt);
-			args.push("--system-prompt", promptPath);
-		}
-	}
-
-	const model = options.model ?? agent?.model;
-	if (model) args.push("--model", model);
-	if (options.thinking) args.push("--thinking", options.thinking);
-	if (agent?.tools && !forkFrom && !sessionFile) args.push("--tools", agent.tools.join(","));
-	return args;
-}
-
-export interface ChildOutcome {
-	output: string;
-	toolCalls: number;
-	usage: UsageTotals;
-	failed?: boolean;
-	/**
-	 * What the child actually did, names and short subjects only. Auto mode
-	 * reviews this when the child returns, to catch a sequence whose individual
-	 * steps each passed. Never carries tool output — see auto-mode/actions.ts.
-	 */
-	actions: ChildAction[];
-}
-
-/**
- * A provider failure in a child (auth, billing, rate limit) surfaces ONLY as
- * an assistant message with stopReason "error" in the event stream — stderr
- * stays empty and the process exits normally. Without capturing it, the
- * parent gets "Subagent produced no output (exit code 0)", the exact
- * ambiguous result a weak model confabulates a cause for. The error is
- * cleared by any later successful assistant message, so pi's internal
- * retries don't leave a stale failure.
- */
-export function providerErrorFrom(message: { stopReason?: string; errorMessage?: string } | undefined): string | undefined {
-	if (!message) return undefined;
-	if (message.stopReason !== "error") return undefined;
-	return message.errorMessage || "unknown provider error";
-}
-
-/** The outcome a finished child resolves to, given everything its stream said. */
-export function closeOutcome(args: {
-	finalText: string;
-	providerError?: string;
-	code: number | null;
-	closeSignal: NodeJS.Signals | null;
-	stderr: string;
-	toolCalls: number;
-	usage: UsageTotals;
-	actions: ChildAction[];
-}): ChildOutcome {
-	const { finalText, providerError, code, closeSignal, stderr, toolCalls, usage, actions } = args;
-	const output = finalText.slice(0, OUTPUT_CAP);
-	if (providerError) {
-		return {
-			output: output.trim()
-				? `${output}\n\n[The subagent's last request ended with a provider error: ${providerError}]`
-				: `Subagent failed with a provider error (its model could not be called — an auth/billing/rate-limit problem, not a task failure): ${providerError}`,
-			toolCalls,
-			usage,
-			actions,
-			failed: true,
-		};
-	}
-	if (output.trim()) {
-		return { output, toolCalls, usage, actions };
-	}
-	const why = closeSignal ? `terminated by ${closeSignal}` : `exit code ${code}`;
-	const detail = stderr.trim().split("\n").slice(-5).join("\n");
-	return {
-		output: `Subagent produced no output (${why}).${detail ? `\n${detail}` : ""}`,
-		toolCalls,
-		usage,
-		actions,
-		failed: true,
-	};
-}
-
-export interface ChildHandle {
-	result: Promise<ChildOutcome>;
-	kill(): void;
-	snapshot(): { toolCalls: number; text: string; usage: UsageTotals };
-}
-
-export function startChild(options: ChildOptions): ChildHandle {
-	const { cwd, signal, onProgress } = options;
-	const task = options.forkFrom ? forkTaskMessage(options.task) : options.task;
-	const args = ["--mode", "json", "-p", ...buildChildFlags(options), task];
-
-	const invocation = piInvocation(args);
-	const child = spawn(invocation.command, invocation.args, {
-		cwd,
-		shell: false,
-		stdio: ["ignore", "pipe", "pipe"],
-		env: { ...process.env, PI_SUBAGENT_CHILD: "1" },
-	});
-
-	let buffer = "";
-	let finalText = "";
-	let toolCalls = 0;
-	const actions: ChildAction[] = [];
-	let stderr = "";
-	let providerError: string | undefined;
-	const usage = emptyUsage();
-
-	const onAbort = () => child.kill("SIGTERM");
-	signal?.addEventListener("abort", onAbort, { once: true });
-
-	const processLine = (line: string) => {
-		if (!line.trim()) return;
-		let event: {
-			type?: string;
-			message?: { role?: string; content?: unknown; usage?: unknown; stopReason?: string; errorMessage?: string };
-		};
-		try {
-			event = JSON.parse(line);
-		} catch {
-			return;
-		}
-		if (event.type === "tool_execution_end") {
-			const toMain = toMainMessage(event);
-			if (toMain) options.onMessageToMain?.(toMain.message, toMain.summary);
-		} else if (event.type === "tool_execution_start") {
-			toolCalls++;
-			const start = event as { toolName?: string; args?: unknown };
-			if (start.toolName) recordAction(actions, start.toolName, start.args);
-			onProgress(toolCalls, finalText, usage);
-		} else if (event.type === "message_end" && event.message?.role === "assistant") {
-			addUsage(usage, event.message.usage);
-			providerError = providerErrorFrom(event.message);
-			const blocks = Array.isArray(event.message.content) ? event.message.content : [];
-			const text = blocks
-				.filter((b): b is { type: string; text: string } => (b as { type?: string }).type === "text")
-				.map((b) => b.text)
-				.join("");
-			if (text.trim()) finalText = text;
-			onProgress(toolCalls, finalText, usage);
-		}
-	};
-
-	const result = new Promise<ChildOutcome>((resolve) => {
-		child.stdout.on("data", (chunk: Buffer) => {
-			buffer += chunk.toString();
-			let idx: number;
-			while ((idx = buffer.indexOf("\n")) !== -1) {
-				processLine(buffer.slice(0, idx));
-				buffer = buffer.slice(idx + 1);
-			}
-		});
-		child.stderr.on("data", (chunk: Buffer) => {
-			stderr += chunk.toString();
-		});
-
-		child.on("error", (error) => {
-			signal?.removeEventListener("abort", onAbort);
-			resolve({ output: `Failed to start subagent: ${error.message}`, toolCalls, usage, actions, failed: true });
-		});
-
-		child.on("close", (code, closeSignal) => {
-			signal?.removeEventListener("abort", onAbort);
-			if (buffer.trim()) processLine(buffer);
-			resolve(closeOutcome({ finalText, providerError, code, closeSignal, stderr, toolCalls, usage, actions }));
-		});
-	});
-
-	return {
-		result,
-		kill: () => child.kill("SIGTERM"),
-		snapshot: () => ({ toolCalls, text: finalText, usage }),
-	};
-}
-
-export interface RpcChildOptions extends Omit<ChildOptions, "task" | "signal" | "onProgress"> {
-	onProgress: (toolCalls: number, lastText: string, usage: UsageTotals) => void;
-	/** Fires at the end of EVERY turn (initial task and later messages alike). */
-	onTurnEnd: (outcome: ChildOutcome) => void;
-	onExit?: () => void;
-}
-
-export interface RpcChildHandle {
-	/**
-	 * Deliver a message. "started" = the child was idle and this began a new
-	 * turn (onTurnEnd will fire for it); "steered" = the child was mid-turn and
-	 * the message joined it (covered by that turn's onTurnEnd).
-	 */
-	send(message: string): "started" | "steered";
-	busy(): boolean;
-	exited(): boolean;
-	kill(): void;
-	snapshot(): { toolCalls: number; text: string; usage: UsageTotals };
-}
-
-/**
- * Resident child over `pi --mode rpc`: same event stream as json mode, plus a
- * stdin command channel — which is what makes messaging a *running* agent
- * possible (`streamingBehavior: "steer"` queues into the current turn; when
- * idle the same command starts a new turn, so there is no idle/busy race).
- * RPC children have hasUI=true, so extension_ui_request dialogs must be
- * answered: every one is cancelled, which reproduces print-mode's
- * non-interactive fallback (gated tools deny instead of deadlocking).
- */
-export function startRpcChild(options: RpcChildOptions): RpcChildHandle {
-	const args = ["--mode", "rpc", ...buildChildFlags(options)];
-	const invocation = piInvocation(args);
-	const child = spawn(invocation.command, invocation.args, {
-		cwd: options.cwd,
-		shell: false,
-		stdio: ["pipe", "pipe", "pipe"],
-		env: { ...process.env, PI_SUBAGENT_CHILD: "1" },
-	});
-
-	const tracker = new RpcTurnTracker();
-	let buffer = "";
-	let stderr = "";
-	let exited = false;
-	/**
-	 * Messages accepted while a prompt was sent but the child's agent loop had
-	 * not started yet (it boots for a few seconds) — a steer written in that
-	 * window would run as its own turn instead of joining the pending one.
-	 * Flushed as steers the moment the child reports agent_start.
-	 */
-	let earlySteers: string[] = [];
-
-	const send = (command: Record<string, unknown>) => {
-		try {
-			child.stdin.write(`${JSON.stringify(command)}\n`);
-		} catch {
-			// A dead pipe surfaces via the close handler.
-		}
-	};
-
-	child.stdout.on("data", (chunk: Buffer) => {
-		buffer += chunk.toString();
-		let idx: number;
-		while ((idx = buffer.indexOf("\n")) !== -1) {
-			const line = buffer.slice(0, idx);
-			buffer = buffer.slice(idx + 1);
-			const action = tracker.process(line);
-			if (!action) continue;
-			if (action.kind === "ui_request") {
-				send({ type: "extension_ui_response", id: action.id, cancelled: true });
-			} else if (action.kind === "stream_start") {
-				for (const message of earlySteers) {
-					send({ type: "prompt", message, streamingBehavior: "steer" });
-				}
-				earlySteers = [];
-			} else if (action.kind === "progress") {
-				options.onProgress(tracker.toolCalls, tracker.turnText, tracker.usage);
-			} else if (action.kind === "message_to_main") {
-				options.onMessageToMain?.(action.message, action.summary);
-			} else if (action.kind === "turn_end") {
-				options.onTurnEnd(turnOutcome());
-			}
-		}
-	});
-	child.stderr.on("data", (chunk: Buffer) => {
-		stderr += chunk.toString();
-	});
-
-	const turnOutcome = (): ChildOutcome => {
-		const output = tracker.turnText.slice(0, OUTPUT_CAP);
-		if (tracker.providerError) {
-			return {
-				output: output.trim()
-					? `${output}\n\n[The subagent's last request ended with a provider error: ${tracker.providerError}]`
-					: `Subagent failed with a provider error (its model could not be called — an auth/billing/rate-limit problem, not a task failure): ${tracker.providerError}`,
-				toolCalls: tracker.toolCalls,
-				usage: tracker.usage,
-				actions: tracker.actions,
-				failed: true,
-			};
-		}
-		if (output.trim()) return { output, toolCalls: tracker.toolCalls, usage: tracker.usage, actions: tracker.actions };
-		const detail = stderr.trim().split("\n").slice(-5).join("\n");
-		return {
-			output: `Subagent produced no output.${detail ? `\n${detail}` : ""}`,
-			toolCalls: tracker.toolCalls,
-			usage: tracker.usage,
-			actions: tracker.actions,
-			failed: true,
-		};
-	};
-
-	const onClose = () => {
-		if (exited) return;
-		exited = true;
-		if (tracker.busy) {
-			tracker.busy = false;
-			const detail = stderr.trim().split("\n").slice(-5).join("\n");
-			const provider = tracker.providerError ? `\nLast provider error: ${tracker.providerError}` : "";
-			options.onTurnEnd({
-				output: `Subagent exited mid-turn.${provider}${detail ? `\n${detail}` : ""}`,
-				toolCalls: tracker.toolCalls,
-				usage: tracker.usage,
-				actions: tracker.actions,
-				failed: true,
-			});
-		}
-		options.onExit?.();
-	};
-	child.on("close", onClose);
-	child.on("error", onClose);
-
-	return {
-		send(message: string): "started" | "steered" {
-			if (exited) throw new Error("subagent process has exited");
-			if (!tracker.busy) {
-				tracker.beginTurn();
-				send({ type: "prompt", message, streamingBehavior: "steer" });
-				return "started";
-			}
-			if (tracker.streaming) {
-				send({ type: "prompt", message, streamingBehavior: "steer" });
-			} else {
-				earlySteers.push(message);
-			}
-			return "steered";
-		},
-		busy: () => tracker.busy,
-		exited: () => exited,
-		kill: () => child.kill("SIGTERM"),
-		snapshot: () => ({
-			toolCalls: tracker.toolCalls,
-			text: tracker.busy && tracker.turnText ? `${tracker.transcript ? `${tracker.transcript}\n\n---\n\n` : ""}${tracker.turnText}` : tracker.transcript,
-			usage: tracker.usage,
-		}),
-	};
-}