@335g/pi-herdr-fleet 0.0.1

package/audit.ts

@@ -0,0 +1,153 @@
+/**
+ * audit: herdr's lifecycle as Pi session entries.
+ *
+ * herdr keeps no history. A pane that became blocked, a worktree that was made
+ * and later thrown away — each is gone the moment the next one arrives, and a
+ * month later "why did we abandon that worktree?" has nothing left to answer it.
+ *
+ * Pi's session JSONL, on the other hand, stays, and `session_search` indexes it.
+ * Writing herdr's events down as they happen is what makes the fleet's past
+ * findable afterwards.
+ *
+ * The entries carry `customType: "herdr-event"` and never enter the model's
+ * context; they exist to be read back by a human or by search.
+ *
+ * Noise is the whole risk of a log like this, so it is cut three ways: only the
+ * events worth finding are subscribed to (the broker owns the one subscription),
+ * `describe` refuses the rest a second time, and a repeated state for one pane
+ * is dropped — herdr re-announces a status after a reconnect, and this is a
+ * history of transitions, not of re-reads.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+
+import type { HerdrEvent } from "./herdr-client.ts";
+
+/** The `customType` of every entry this module writes. */
+export const AUDIT_CUSTOM_TYPE = "herdr-event";
+
+/**
+ * One entry's `data`. `summary` is the line the renderer shows and the string a
+ * literal search finds, so it carries the whole point of the entry.
+ */
+export interface AuditData {
+	/** herdr's event kind, as the schema spells it: `worktree_created`, ... */
+	event: string;
+	summary: string;
+	at: string;
+	pane_id?: string;
+	workspace_id?: string;
+	agent?: string;
+	agent_status?: string;
+	branch?: string;
+	path?: string;
+	forced?: boolean;
+}
+
+export type EntryAppender = (customType: string, data: AuditData) => void;
+
+function text(value: unknown): string | undefined {
+	return typeof value === "string" && value !== "" ? value : undefined;
+}
+
+/**
+ * What one event is worth, or `undefined` when it is not worth an entry.
+ *
+ * herdr spells the envelope's `event` two ways: the pane-scoped subscriptions
+ * push the dotted name (`pane.agent_status_changed`) while the lifecycle events
+ * push the schema's underscored kind (`worktree_created`). Normalizing first
+ * means neither spelling can slip past the switch.
+ */
+export function describe(event: HerdrEvent): AuditData | undefined {
+	const data: Record<string, any> = event.data ?? {};
+	const name = event.event.replace(/\./g, "_");
+	const at = new Date().toISOString();
+	const worktree = data.worktree ?? {};
+	const branch = text(worktree.branch);
+	const path = text(worktree.path);
+	const workspace = data.workspace ?? {};
+	const workspaceId = text(workspace.workspace_id) ?? text(data.workspace_id) ?? text(worktree.open_workspace_id);
+
+	switch (name) {
+		case "worktree_created":
+			return { event: name, at, summary: `worktree created ${branch ?? path ?? "?"}`, branch, path, workspace_id: workspaceId };
+		case "worktree_removed": {
+			const forced = data.forced === true;
+			return {
+				event: name,
+				at,
+				summary: `worktree removed ${branch ?? path ?? "?"}${forced ? " (forced)" : ""}`,
+				branch,
+				path,
+				workspace_id: workspaceId,
+				forced,
+			};
+		}
+		case "workspace_created": {
+			const id = text(workspace.workspace_id);
+			const label = text(workspace.label) ?? id ?? "?";
+			return { event: name, at, summary: `workspace created ${label} (${id ?? "?"})`, workspace_id: id, path: text(workspace.worktree?.checkout_path) };
+		}
+		case "workspace_closed":
+			return { event: name, at, summary: `workspace closed ${workspaceId ?? "?"}`, workspace_id: workspaceId };
+		case "pane_agent_status_changed": {
+			const paneId = text(data.pane_id);
+			const status = text(data.agent_status);
+			if (!paneId || !status) return undefined;
+			const agent = text(data.display_agent) ?? text(data.agent);
+			return {
+				event: name,
+				at,
+				summary: `${paneId} ${status}${agent ? ` (${agent})` : ""}`,
+				pane_id: paneId,
+				workspace_id: text(data.workspace_id),
+				agent,
+				agent_status: status,
+			};
+		}
+		// `pane_output_changed`, `pane_scroll_changed`, `layout_updated`, the tab
+		// and pane inventory events: high-frequency, or already on screen. None of
+		// them is subscribed to; this is the second refusal.
+		default:
+			return undefined;
+	}
+}
+
+/** Turns the events the broker forwards into entries, one per real transition. */
+export class AuditLog {
+	private readonly append: EntryAppender;
+	private readonly selfPaneId: string;
+	/** The last state written per pane. */
+	private readonly lastStatus = new Map<string, string>();
+
+	constructor(append: EntryAppender, selfPaneId: string) {
+		this.append = append;
+		this.selfPaneId = selfPaneId;
+	}
+
+	/** One event in, at most one entry out. */
+	record(event: HerdrEvent): void {
+		const entry = describe(event);
+		if (!entry) return;
+		if (entry.pane_id !== undefined) {
+			// This extension's own pane is the session doing the logging; its turns
+			// are already in the transcript.
+			if (entry.pane_id === this.selfPaneId) return;
+			const status = entry.agent_status ?? "";
+			if (this.lastStatus.get(entry.pane_id) === status) return;
+			this.lastStatus.set(entry.pane_id, status);
+		}
+		this.append(AUDIT_CUSTOM_TYPE, entry);
+	}
+}
+
+/** Fold an audit entry into the one line that says what happened. */
+export function registerAuditRenderer(pi: ExtensionAPI): void {
+	pi.registerEntryRenderer<AuditData>(AUDIT_CUSTOM_TYPE, (entry, { expanded }, theme) => {
+		const data = entry.data;
+		const line = `${theme.fg("dim", "[herdr]")} ${data?.summary ?? "event"}`;
+		if (!expanded) return new Text(line, 0, 0);
+		return new Text(`${line}\n${theme.fg("dim", JSON.stringify(data, null, 2))}`, 0, 0);
+	});
+}

package/clean.ts

@@ -0,0 +1,256 @@
+/**
+ * clean: the one implementation behind the `fleet_clean` tool and
+ * `/fleet clean`.
+ *
+ * Merging deliberately leaves the worktree in place (§3c), so something has to
+ * remove what the loop created: the worktree, the branch, and the panes the run
+ * recorded. This is that operation, and it is a separate call rather than a side
+ * effect of merging because the worktree is also where the reviewer ran and
+ * where the author's session may still be.
+ *
+ * Two things are deliberately *not* removed: the run record and the session
+ * JSONL. The record is what makes "why did we abandon that worktree?" answerable
+ * later, and the session is what `session_search` indexes; both compound, and a
+ * cleanup that erased them would make the audit log (§6) write-only. The record
+ * gets a `cleanedAt` timestamp instead.
+ *
+ * A run may only be cleaned once its branch is in the main checkout's history —
+ * the record's `mergedAt`, or `git merge-base --is-ancestor`. `force` overrides
+ * that, and switches the branch deletion from `git branch -d` to `-D`. Removing
+ * a worktree herdr no longer knows about, a branch that is already gone, or a
+ * pane that is already closed is not an error: the operation is idempotent.
+ */
+
+import { join } from "node:path";
+
+import { Type } from "@earendil-works/pi-ai";
+import type { ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
+
+import { type HerdrClient, type Outcome, err, ok } from "./herdr-client.ts";
+import { isMerged, readRun, runFileName, runsDir, updateRun } from "./runs.ts";
+import { type CommandRunner, mainCheckout } from "./worktree.ts";
+
+const GIT_TIMEOUT_MS = 30_000;
+/**
+ * `worktree.remove` deletes a whole checkout, `node_modules` included, so the
+ * client has to outlast that. The transport's 5s default is a client-side
+ * timeout, not herdr's own speed: at 5s herdr finished the removal anyway while
+ * this side reported a failure, and the `git branch -d` that followed failed on
+ * a worktree that was already gone.
+ */
+const WORKTREE_REMOVE_TIMEOUT_MS = 120_000;
+/** After a client timeout, how long to give herdr before looking at its state. */
+const WORKTREE_CONFIRM_DELAY_MS = 2_000;
+const WORKTREE_LIST_TIMEOUT_MS = 10_000;
+
+export interface CleanRequest {
+	/** Any directory in the repository; the branch is deleted in the main checkout. */
+	cwd: string;
+	branch: string;
+	/** Clean even without a merge, and delete the branch with `-D`. */
+	force?: boolean;
+}
+
+export interface CleanResult {
+	branch: string;
+	main: string;
+	/** False when herdr had no such worktree, or could not remove it. */
+	worktreeRemoved: boolean;
+	/** False when the branch was already gone. */
+	branchDeleted: boolean;
+	/** The panes the record named that were closed, this session's own excluded. */
+	panesClosed: string[];
+	/** What did not happen, in the caller's language. Never a refusal. */
+	warnings: string[];
+}
+
+/**
+ * `/fleet clean`: the merge check, then the panes, the worktree and the branch.
+ *
+ * The panes go first. `worktree.remove` closes the workspace and everything in
+ * it, so a pane close attempted afterwards would always look like a failure; in
+ * this order a normal cleanup has nothing to report. A pane this session runs in
+ * is never closed — that is the session doing the cleaning.
+ */
+export async function cleanRun(
+	client: HerdrClient,
+	run: CommandRunner,
+	request: CleanRequest,
+): Promise<Outcome<CleanResult>> {
+	const branch = request.branch.trim();
+	if (branch === "") return err("clean: a branch is required");
+	const main = await mainCheckout(run, request.cwd);
+	if (!main) return err(`clean: ${request.cwd} is not inside a git checkout`);
+
+	// The record is what names the worktree and the panes, so without one there is
+	// nothing to clean — and a branch deleted behind herdr's back would leave its
+	// worktree dangling.
+	const record = readRun(main, branch);
+	if (!record) {
+		return err(`clean: no run was recorded for ${branch} in ${runsDir(main)}; fleet_clean only removes what fleet_fork created`);
+	}
+
+	// A run that was already cleaned stays cleanable: the merge check is about the
+	// first cleanup, and refusing the second would make the operation fail on the
+	// very state it created.
+	const merged = record.cleanedAt !== undefined || record.mergedAt !== undefined || (await isMerged(run, main, branch));
+	if (!merged && request.force !== true) {
+		return err(`clean: ${branch} has not been merged; merge it first, or pass force to remove it anyway`);
+	}
+
+	const warnings: string[] = [];
+
+	const panesClosed: string[] = [];
+	const self = client.selfPaneId();
+	for (const paneId of namedPanes(record)) {
+		if (paneId === self) continue;
+		const closed = await client.request("pane.close", { pane_id: paneId });
+		if (closed.ok) panesClosed.push(paneId);
+		else warnings.push(`the pane ${paneId} was not closed: ${closed.error}`);
+	}
+
+	let worktreeRemoved = false;
+	if (record.workspaceId) {
+		// `force` here is herdr's, not the gate's: a merged worktree still has the
+		// untracked environment (`node_modules`, `.env`) that made it usable.
+		const removed = await client.request(
+			"worktree.remove",
+			{ workspace_id: record.workspaceId, force: true },
+			WORKTREE_REMOVE_TIMEOUT_MS,
+		);
+		if (removed.ok) {
+			worktreeRemoved = true;
+		} else if (removed.code === "timeout" && (await confirmRemoved(client, main, record))) {
+			// The client gave up; herdr did not. A client-side timeout is not herdr's
+			// failure, so herdr's own state decides — the branch delete below would fail
+			// on a worktree that is really still there, not on one that is really gone.
+			worktreeRemoved = true;
+			warnings.push(
+				`the worktree (${record.workspaceId}) was removed, but herdr did not answer within ${WORKTREE_REMOVE_TIMEOUT_MS}ms`,
+			);
+		} else {
+			warnings.push(`the worktree (${record.workspaceId}) was not removed: ${removed.error}`);
+		}
+	} else {
+		warnings.push("the run recorded no workspace, so no worktree was removed");
+	}
+
+	let branchDeleted = false;
+	if (await branchExists(run, main, branch)) {
+		const deleted = await run("git", ["branch", request.force === true ? "-D" : "-d", branch], {
+			cwd: main,
+			timeout: GIT_TIMEOUT_MS,
+		});
+		if (deleted.code !== 0) {
+			const reason = firstLine(deleted.stderr) ?? `exit ${deleted.code}`;
+			// The branch delete is often the first step that can fail after the worktree
+			// is gone, and the reason is usually a warning collected above: a worktree
+			// herdr could not remove still has the branch checked out, and git's own
+			// message then points at git rather than at herdr. The warnings carry the
+			// root cause, so they go into the error instead of being dropped.
+			const context = warnings.length === 0 ? "" : `; before it: ${warnings.join("; ")}`;
+			// The record is the audit trail, so a cleanup that stopped half way has to
+			// say so: `cleanedAt` stays unset, and `cleanError` carries the reason and
+			// the stages that did run. Without it the panes would be closed and the
+			// worktree gone while the record still read as an untouched run. A later
+			// clean that finishes clears the field again.
+			const progress = `panes closed: ${panesClosed.length === 0 ? "none" : panesClosed.join(", ")}; worktree removed: ${worktreeRemoved}`;
+			updateRun(main, branch, { cleanError: `${reason} (${progress})` });
+			return err(
+				`clean: git branch ${request.force === true ? "-D" : "-d"} ${branch} failed: ${reason}${context}`,
+			);
+		}
+		branchDeleted = true;
+	}
+
+	// The record stays. It is the audit trail, and `cleanedAt` is what says the
+	// rest of it is history rather than live state. `cleanError` is cleared by a
+	// clean that did finish, so a stale failure is not read as a live one.
+	updateRun(main, branch, { cleanedAt: new Date().toISOString(), cleanError: undefined });
+
+	return ok({ branch, main, worktreeRemoved, branchDeleted, panesClosed, warnings });
+}
+
+/** The panes the record names: the author's, then the reviewer's, without repeats. */
+function namedPanes(record: { paneId?: string; reviewer?: { paneId: string } }): string[] {
+	return [...new Set([record.paneId, record.reviewer?.paneId].filter((id): id is string => typeof id === "string" && id !== ""))];
+}
+
+/**
+ * Whether herdr's own worktree list still has the recorded checkout.
+ *
+ * A client timeout says only that this side stopped waiting; the list is what
+ * says whether herdr finished. The path is the worktree's identity, and it is
+ * also what the branch delete cares about: a worktree git still has registered
+ * keeps the branch checked out.
+ */
+async function confirmRemoved(
+	client: HerdrClient,
+	main: string,
+	record: { path: string },
+): Promise<boolean> {
+	await new Promise((resolve) => setTimeout(resolve, WORKTREE_CONFIRM_DELAY_MS));
+	const listed = await client.request("worktree.list", { cwd: main }, WORKTREE_LIST_TIMEOUT_MS);
+	if (!listed.ok) return false;
+	const worktrees: any[] = Array.isArray(listed.value?.worktrees) ? listed.value.worktrees : [];
+	return !worktrees.some((candidate) => candidate?.path === record.path);
+}
+
+/** Whether the branch still exists, so an already-deleted one is not an error. */
+async function branchExists(run: CommandRunner, main: string, branch: string): Promise<boolean> {
+	const found = await run("git", ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`], { cwd: main, timeout: GIT_TIMEOUT_MS });
+	return found.code === 0;
+}
+
+function firstLine(text: string): string | undefined {
+	return text.split("\n").find((line) => line.trim() !== "")?.trim();
+}
+
+// ------------------------------------------------------------------ the tool
+
+const CLEAN_PARAMETERS = Type.Object({
+	branch: Type.String({
+		description: "The branch of the run to clean. A run must have been recorded for it by fleet_fork.",
+	}),
+	force: Type.Optional(
+		Type.Boolean({
+			description:
+				"Clean even though the branch has not been merged, and delete it with `git branch -D` instead of `-d`. Defaults to false.",
+		}),
+	),
+});
+
+/**
+ * The tool an agent calls once a branch is merged. `/fleet clean` is a thin
+ * wrapper over `cleanRun`, the same function this calls.
+ */
+export function fleetCleanTool(client: HerdrClient, run: CommandRunner): ToolDefinition<typeof CLEAN_PARAMETERS> {
+	return {
+		name: "fleet_clean",
+		label: "Fleet clean",
+		description:
+			"Remove what a merged run created: its worktree through herdr's worktree.remove, its branch with `git branch -d` in the main checkout, and the panes the run recorded. It presumes the branch is already merged — the record's mergedAt, or `git merge-base --is-ancestor` — and refuses otherwise; pass force to clean an unmerged run anyway and delete its branch with -D. The run record and the session JSONL are never deleted: the record gets a cleanedAt timestamp on success, and a cleanup that could not finish leaves the reason in cleanError instead. Already-removed worktrees, branches and panes are not an error.",
+		promptSnippet: "Remove a merged run's worktree, branch and panes, keeping its record",
+		promptGuidelines: [
+			"Call fleet_clean after fleet_merge to remove the worktree, branch and panes the run left behind.",
+			"Only a merged run may be cleaned; set force only when the human asks for it, and say why.",
+			"fleet_clean keeps the run record and the session JSONL; it only adds cleanedAt.",
+		],
+		parameters: CLEAN_PARAMETERS,
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx: ExtensionContext) {
+			if (ctx.mode !== "tui") throw new Error("fleet_clean only works in an interactive Pi session");
+			const cleaned = await cleanRun(client, run, { cwd: ctx.cwd, branch: params.branch, force: params.force });
+			if (!cleaned.ok) throw new Error(cleaned.error);
+			const lines = [
+				`cleaned ${cleaned.value.branch}`,
+				`worktree: ${cleaned.value.worktreeRemoved ? "removed" : "nothing to remove"}`,
+				`branch: ${cleaned.value.branchDeleted ? "deleted" : "already gone"}`,
+				`panes closed: ${cleaned.value.panesClosed.length === 0 ? "none" : cleaned.value.panesClosed.join(", ")}`,
+				`record: ${join(runsDir(cleaned.value.main), runFileName(cleaned.value.branch))}`,
+			];
+			for (const warning of cleaned.value.warnings) lines.push(`warning: ${warning}`);
+			lines.push("the run record and the session JSONL were kept; the record only gained cleanedAt");
+			return { content: [{ type: "text" as const, text: lines.join("\n") }], details: cleaned.value };
+		},
+	};
+}

package/fork.ts

@@ -0,0 +1,216 @@
+/**
+ * fork: the one implementation behind the `fleet_fork` tool and `/fleet fork`.
+ *
+ * The tool is the primary caller. The loop this extension exists for is driven
+ * by an agent — fork, review, merge — and a command alone would put a human in
+ * the middle of every step, which is where a shell script already is. The
+ * command stays as a thin wrapper for the times a human does want to type it.
+ *
+ * Both go through `forkWorktree`, so there is exactly one order of operations to
+ * keep right, and the arguments the tool receives are validated here rather than
+ * trusted: the caller is a model.
+ */
+
+import { StringEnum, Type } from "@earendil-works/pi-ai";
+import type { ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
+
+import { type HerdrClient, type Outcome, err, ok } from "./herdr-client.ts";
+import { type RunRecord, writeRun } from "./runs.ts";
+import { findScope, forkScopeIds, scopeIds } from "./scopes.ts";
+import {
+	type CommandRunner,
+	type EnvPropagation,
+	type InstallOutcome,
+	agentName,
+	createWorktree,
+	mainCheckout,
+	prepareWorktree,
+	sendSeed,
+	startAgent,
+} from "./worktree.ts";
+
+export interface ForkRequest {
+	/** The directory the worktree is created from: a checkout of the repository. */
+	cwd: string;
+	branch: string;
+	/** The task the forked session works on. It is the whole brief. */
+	task: string;
+	base?: string;
+	/** Scope id. Defaults to `implementation`. */
+	scope?: string;
+	/** Install dependencies when the checkout has a lockfile. Defaults to true. */
+	install?: boolean;
+	/** Split a pane and start Pi in it. Defaults to true. */
+	start?: boolean;
+}
+
+export interface ForkedWorktree {
+	path: string;
+	branch: string;
+	workspaceId: string;
+	/** The ref the branch was cut from, once it is known. */
+	base?: string;
+	/** The session that was started, when `start` was true. */
+	session?: { paneId: string; agent: string };
+	/** Absent when nothing needed installing, or installation was skipped. */
+	install?: InstallOutcome;
+	env: EnvPropagation;
+	/** Warnings about the checkout itself: the environment has its own, in `env`. */
+	warnings: string[];
+}
+
+/**
+ * The five steps of §3a, in order. `run` is only used for `direnv`; everything
+ * that happens in herdr goes through the socket.
+ */
+export async function forkWorktree(
+	client: HerdrClient,
+	run: CommandRunner,
+	request: ForkRequest,
+): Promise<Outcome<ForkedWorktree>> {
+	// The tool's caller is an agent, so the empty string is the shape a missing
+	// argument usually takes: a field the model filled in with nothing.
+	const branch = request.branch.trim();
+	const task = request.task.trim();
+	if (branch === "" || task === "") return err("fork: branch and task are both required");
+
+	const scopeId = request.scope?.trim() || "implementation";
+	const scope = findScope(scopeId);
+	if (!scope) return err(`fork: unknown scope ${scopeId} (a fork can use ${forkScopeIds().join(", ")})`);
+	// A fork has a task and a worktree and nothing else, so a scope that needs
+	// material gathered from an existing worktree is not one it can start.
+	if (!scope.forkable) return err(`fork: the ${scopeId} scope is not started by a fork (a fork can use ${forkScopeIds().join(", ")})`);
+
+	const base = request.base?.trim() || undefined;
+	const created = await createWorktree(client, run, { cwd: request.cwd, branch, base, label: branch });
+	if (!created.ok) return created;
+	const { env, path, workspaceId, rootPaneId, warnings } = created.value;
+	// Everything past this point has to say that the checkout is already there,
+	// because it is: a failed fork leaves a worktree behind.
+	const afterCreate = (error: string) => `fork: ${error} (the worktree at ${path} was created)`;
+	const forked: ForkedWorktree = { path, branch: created.value.branch ?? branch, workspaceId, base: created.value.base, env, warnings };
+	// The run record is the only state 3c keeps: it is what a review updates and
+	// what the merge gate reads. Failing to write it is a warning, not a failed
+	// fork — the worktree and the session are already real.
+	const recordRun = async (): Promise<void> => {
+		const main = await mainCheckout(run, request.cwd);
+		if (!main) {
+			forked.warnings.push("the run record could not be written: no main checkout was found");
+			return;
+		}
+		const record: RunRecord = {
+			branch: forked.branch,
+			base: forked.base,
+			path,
+			workspaceId,
+			paneId: forked.session?.paneId,
+			agentName: forked.session?.agent,
+			scope: scope.id,
+			task,
+			createdAt: new Date().toISOString(),
+		};
+		try {
+			writeRun(main, record);
+		} catch (error) {
+			forked.warnings.push(`the run record could not be written: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	};
+
+	if (request.start === false) {
+		await recordRun();
+		return ok(forked);
+	}
+
+	const prepared = await prepareWorktree(client, {
+		path,
+		workspaceId,
+		rootPaneId,
+		install: request.install !== false,
+	});
+	if (!prepared.ok) return err(afterCreate(prepared.error));
+	forked.install = prepared.value.install;
+
+	// The pane surface, not `agent.prompt`: see §2 of DESIGN.md.
+	const paneId = prepared.value.paneId;
+	const agent = agentName(forked.branch);
+	const started = await startAgent(client, { paneId, name: agent });
+	if (!started.ok) return err(afterCreate(started.error));
+
+	const sent = await sendSeed(client, paneId, scope.seed({ task, path, branch: forked.branch, base }));
+	if (!sent.ok) return err(afterCreate(sent.error));
+	forked.session = { paneId, agent };
+
+	await recordRun();
+	return ok(forked);
+}
+
+/** The scope ids a fork can use, so the schema and the registry cannot drift apart. */
+const FORK_SCOPE_IDS = forkScopeIds();
+
+const FORK_PARAMETERS = Type.Object({
+	branch: Type.String({ description: "Branch name for the new worktree. Created if it does not exist." }),
+	task: Type.String({
+		description:
+			"The task the forked session works on, in full. It is the whole brief: the forking session's conversation is not passed on, so anything already decided has to be written here.",
+	}),
+	base: Type.Optional(Type.String({ description: "Ref to branch from. Defaults to HEAD." })),
+	scope: Type.Optional(
+		StringEnum(FORK_SCOPE_IDS, { description: `What kind of session to fork. Defaults to implementation. Known scopes: ${scopeIds()}.` }),
+	),
+	install: Type.Optional(
+		Type.Boolean({ description: "Install dependencies in the worktree when it has a lockfile. Defaults to true." }),
+	),
+	start: Type.Optional(
+		Type.Boolean({ description: "Open a pane and start Pi in the worktree. Defaults to true; false only creates the worktree." }),
+	),
+});
+
+/** The tool the agent calls. Registered in a TUI session only, like the command. */
+export function fleetForkTool(client: HerdrClient, run: CommandRunner): ToolDefinition<typeof FORK_PARAMETERS> {
+	return {
+		name: "fleet_fork",
+		label: "Fleet fork",
+		description:
+			"Fork the repository into a new git worktree, start a Pi session in it, and hand it one task. The forked session works there on its own and commits its work; the forking session keeps its conversation to itself, so the task has to carry every decision it needs. Returns the worktree, the branch, the pane and the agent.",
+		promptSnippet: "Fork a worktree, start a Pi session in it, and hand it a task",
+		promptGuidelines: [
+			"Use fleet_fork when work should happen in a separate worktree, by a separate Pi session, without blocking this one.",
+			"Write the fleet_fork task as a complete brief: the forked session cannot see this conversation.",
+		],
+		parameters: FORK_PARAMETERS,
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx: ExtensionContext) {
+			if (ctx.mode !== "tui") throw new Error("fleet_fork only works in an interactive Pi session");
+			const forked = await forkWorktree(client, run, {
+				cwd: ctx.cwd,
+				branch: params.branch,
+				task: params.task,
+				base: params.base,
+				scope: params.scope,
+				install: params.install,
+				start: params.start,
+			});
+			// A tool reports failure by throwing; a returned value never sets the
+			// error flag, and the model has to know the fork did not happen.
+			if (!forked.ok) throw new Error(forked.error);
+			return { content: [{ type: "text" as const, text: report(forked.value) }], details: forked.value };
+		},
+	};
+}
+
+/**
+ * The tool result becomes one entry in the conversation, so it stays short: what
+ * was created, and only the warnings — a fork that carried the environment over
+ * cleanly has nothing to say about it.
+ */
+function report(forked: ForkedWorktree): string {
+	const lines = [`forked ${forked.branch}`, `worktree: ${forked.path}`, `workspace: ${forked.workspaceId}`];
+	if (forked.session) lines.push(`pane: ${forked.session.paneId}`, `agent: ${forked.session.agent}`);
+	else lines.push("no pane was started");
+	if (forked.install) {
+		const { command, error, ok } = forked.install;
+		lines.push(`prepare: ${ok ? `${command} finished` : `${command} failed (${error})`}`);
+	}
+	for (const warning of forked.warnings) lines.push(`warning: ${warning}`);
+	for (const warning of forked.env.warnings) lines.push(`warning: ${warning}`);
+	return lines.join("\n");
+}