pi-squire 0.9.5 → 0.11.0

package/src/index.ts

@@ -2,11 +2,12 @@
 // window, over the `message:*` hooks.
 //
 // `/delegate <agent> [--model <provider/id>] [--thinking <level>]
-// [--label <name>] [--auto-exit | --no-auto-exit] <task…>`
+// [--label <name>] [--cwd <dir> | --worktree <branch> [--worktree-source <dir>] [--worktree-base <commit-ish>] ] [--auto-exit | --no-auto-exit] <task…>`
 // reads the agent from `<agent dir>/squire/agents/<name>/AGENT.md`, writes the task
 // to the delegate's inbox through `message:send`, emits `session:launch` so
 // listeners can add arguments and environment, then opens a window in the
-// parent's working directory running the parent's own Pi. The window and the
+// parent's working directory, or the existing directory `--cwd` selects
+// (`workspace.ts`), running the parent's own Pi. The window and the
 // session share one name: `<agent>-<label>`, or `<agent>-<first 8 of the id>`
 // without a label. Starting a delegation adds nothing to
 // the model's context. Each delegation is recorded
@@ -20,14 +21,17 @@
 // session has no tool for leaves the agent out of the roster. Its `tools` goes
 // as `--tools` and each of its `extensions` as `-e`, both for the child alone.
 //
-// The model gets three tools. `delegate` takes agent, task and optional model
+// The model gets four tools. `delegate` takes agent, task and optional model
 // and thinking, validates them the way the command does, and starts the
 // delegation at once, opening no dialog, so parallel calls cannot block one
-// another. `delegation_status`
+// another; the one exception is a `cwd` whose project trust is unresolved,
+// which the user answers in the parent. `delegation_status`
 // reports each delegation as running (window open, no result yet), done (with
 // its result status) or closed, with the session name, window, session and
 // envelope paths.
-// `delegation_close` kills the window and records the close. Inside a delegate
+// `delegation_close` kills the window and records the close. `delegation_resume`
+// (`resume.ts`) reopens an exited delegate's session in a new window with a
+// follow-up task, recorded as a new delegation. Inside a delegate
 // (`PI_DELEGATE_PARENT` set) the extension registers only `child.ts`'s
 // `/auto-exit` and handlers, so a delegate cannot delegate.
 //
@@ -36,7 +40,7 @@
 import { randomUUID } from "node:crypto";
 import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { basename, join } from "node:path";
+import { basename, isAbsolute, join } from "node:path";
 
 import {
 	type ExtensionAPI,
@@ -49,11 +53,28 @@ import { Type } from "typebox";
 import { type Agent, isThinking, type Roster, readRoster, THINKING_LEVELS } from "./agents.ts";
 import { AGENT_ENV, AUTO_EXIT_ENV, FALLBACK_ENV, registerChild } from "./child.ts";
 import { activeMark, clearMarks, isFree, readMarks } from "./limits.ts";
-import { renderDelegateCall, renderDelegateResult } from "./render.ts";
-import { createResults, delegateName } from "./results.ts";
-import { createTmuxClient, type TmuxClient } from "./tmux.ts";
+import { dirtyNotice, renderDelegateCall, renderDelegateResult, resourceLine } from "./render.ts";
+import { createResults, delegateName, type WorkspaceAttempt } from "./results.ts";
+import { createResume, type ResumeRequest, resumableIds, startedLine } from "./resume.ts";
+import { createTmuxClient, type TmuxClient, WindowOpenError } from "./tmux.ts";
 import { createTracking, toolResult } from "./tracking.ts";
 import { createProactive, createUsageClient, type Proactive, type UsageClient } from "./usage.ts";
+import {
+	normalizeWorkspaceValue,
+	prepareDirectory,
+	trustPlannedWorktree,
+	type Workspace,
+	WorkspaceSchema,
+} from "./workspace.ts";
+import {
+	createWorktree,
+	inQueue,
+	prepareWorktree,
+	recoveryCommands,
+	revalidate,
+	rollbackWorktree,
+	type WorktreePlan,
+} from "./worktree.ts";
 
 /** The optional parent guidance file under `<agent dir>/squire/`. */
 const PARENT_PROMPT = "delegation_prompt.md";
@@ -102,7 +123,17 @@ function parentTrust(parent: string): string {
 	].join(" ");
 }
 /** The flags `/delegate` takes before the task. */
-const FLAGS = ["--model", "--thinking", "--label", "--auto-exit", "--no-auto-exit"] as const;
+const FLAGS = [
+	"--model",
+	"--thinking",
+	"--label",
+	"--cwd",
+	"--worktree",
+	"--worktree-base",
+	"--worktree-source",
+	"--auto-exit",
+	"--no-auto-exit",
+] as const;
 
 /** The `delegate` tool's structured result, which is also its details. */
 export const DelegateSchema = Type.Object({
@@ -118,16 +149,42 @@ export const DelegateSchema = Type.Object({
 	autoExit: Type.Boolean(),
 	windowId: Type.String(),
 	windowName: Type.String(),
+	cwd: Type.String({ description: "The directory the delegate's window opened in." }),
+	sessionDir: Type.String({ description: "The session-storage directory the delegate was told to use." }),
+	workspace: WorkspaceSchema,
 });
 
 const NOT_IN_TMUX = "this session is not inside tmux; start it in a tmux pane to open a delegate window";
 
 const USAGE =
-	"usage: /delegate <agent> [--model <provider/id>] [--thinking <level>] [--label <name>] [--auto-exit | --no-auto-exit] <task>";
+	"usage: /delegate <agent> [--model <provider/id>] [--thinking <level>] [--label <name>] [--cwd <dir> | --worktree <branch> [--worktree-source <dir>] [--worktree-base <commit-ish>] ] [--auto-exit | --no-auto-exit] <task>";
+
+/** The flags `/delegate-resume` takes before the task. */
+const RESUME_FLAGS = ["--model", "--thinking", "--auto-exit", "--no-auto-exit"] as const;
+const RESUME_USAGE =
+	"usage: /delegate-resume <id> [--model <provider/id>] [--thinking <level>] [--auto-exit | --no-auto-exit] <task>";
 
 type SendPayload = { to: unknown; body: unknown; envelope?: { id?: unknown }; error?: unknown };
-type LaunchPayload = { args: string[]; env: Record<string, string>; agent: string };
-type Parsed = { agent: string; model?: string; thinking?: string; label?: string; autoExit?: boolean; task: string };
+/** `cwd` is informational: the window opens in the launch's own value, whatever a listener assigns. */
+type LaunchPayload = {
+	args: string[];
+	env: Record<string, string>;
+	agent: string;
+	readonly cwd: string;
+	readonly toolCallId: string | undefined;
+};
+type Parsed = {
+	agent: string;
+	model?: string;
+	thinking?: string;
+	label?: string;
+	cwd?: string;
+	worktree?: string;
+	worktree_base?: string;
+	worktree_source?: string;
+	autoExit?: boolean;
+	task: string;
+};
 /** A request that passed the roster, model, thinking and label checks. */
 type Start = {
 	agent: Agent;
@@ -140,13 +197,30 @@ type Start = {
 	rest: string[];
 	thinking: string;
 	label?: string;
+	/** The existing directory to run in, as given; undefined inherits the parent's. */
+	cwd?: string;
+	/** The new local branch to create a worktree for; undefined creates none. */
+	worktree?: string;
+	worktree_base?: string;
+	worktree_source?: string;
 	autoExit: boolean;
 	task: string;
 };
 /** A candidate model passed over: `why` finishes "<model> is …", `reason` is the long form for a refusal. */
 type Skipped = { model: string; why: string; reason: string };
+/** What opening a delegate's window reads from a request: a `Start`, or the parts of one a resume decides. */
+type ChildStart = Pick<Start, "agent" | "model" | "rest" | "thinking" | "autoExit">;
 /** A delegation that is open in a tmux window. */
-type Launched = { id: string; name: string; windowId: string; windowName: string; requestId: string };
+type Launched = {
+	id: string;
+	name: string;
+	windowId: string;
+	windowName: string;
+	requestId: string;
+	cwd: string;
+	sessionDir: string;
+	workspace: Workspace;
+};
 
 /**
  * Write the appended system prompt to a fresh owner-only directory under the
@@ -206,35 +280,109 @@ function closest(value: string, candidates: readonly string[]): string[] {
 		.map(({ candidate }) => candidate);
 }
 
+/** One whitespace-separated word of `text` at or after `from`, verbatim; undefined at the end. */
+function word(text: string, from: number): { text: string; start: number; end: number } | undefined {
+	const match = /\S+/g;
+	match.lastIndex = from;
+	const found = match.exec(text);
+	return found === null ? undefined : { text: found[0], start: found.index, end: found.index + found[0].length };
+}
+
+/**
+ * A flag's value at or after `from`: a plain word, or a double-quoted string
+ * in which `\"` and `\\` stand for `"` and `\`. No shell expansion of any kind.
+ */
+function flagValue(
+	text: string,
+	from: number,
+	flag: string,
+	usage: string = USAGE,
+): { value: string; end: number } | { error: string } {
+	const next = word(text, from);
+	if (next === undefined || next.text.startsWith("--")) return { error: `${flag} needs a value; ${usage}` };
+	if (!next.text.startsWith('"')) return { value: next.text, end: next.end };
+	let value = "";
+	let i = next.start + 1;
+	while (i < text.length && text[i] !== '"') {
+		const escaped = text[i] === "\\" && (text[i + 1] === '"' || text[i + 1] === "\\");
+		value += escaped ? text[i + 1] : text[i];
+		i += escaped ? 2 : 1;
+	}
+	if (i >= text.length) return { error: `${flag}'s value has no closing quote; ${usage}` };
+	if (i + 1 < text.length && !/\s/.test(text[i + 1])) {
+		return { error: `${flag}'s quoted value must be followed by a space; ${usage}` };
+	}
+	return { value, end: i + 1 };
+}
+
 /** `/delegate`'s arguments: an agent, optional flags, then a verbatim task. */
 function parse(text: string): { parsed: Parsed } | { error: string } {
-	const tokens = [...text.matchAll(/\S+/g)].map((match) => ({ text: match[0], start: match.index }));
-	if (tokens.length === 0) return { error: USAGE };
-	if (tokens[0].text.startsWith("-")) return { error: `the first argument is the agent name; ${USAGE}` };
-	const parsed: Parsed = { agent: tokens[0].text, task: "" };
-	let i = 1;
-	while (i < tokens.length && tokens[i].text.startsWith("-")) {
-		const flag = tokens[i].text;
+	const agent = word(text, 0);
+	if (agent === undefined) return { error: USAGE };
+	if (agent.text.startsWith("-")) return { error: `the first argument is the agent name; ${USAGE}` };
+	const parsed: Parsed = { agent: agent.text, task: "" };
+	let at = agent.end;
+	for (let next = word(text, at); next?.text.startsWith("-"); next = word(text, at)) {
+		const flag = next.text;
 		if (flag === "--auto-exit" || flag === "--no-auto-exit") {
 			parsed.autoExit = flag === "--auto-exit";
-			i += 1;
+			at = next.end;
 			continue;
 		}
-		if (flag !== "--model" && flag !== "--thinking" && flag !== "--label") {
+		if (
+			flag !== "--model" &&
+			flag !== "--thinking" &&
+			flag !== "--label" &&
+			flag !== "--cwd" &&
+			flag !== "--worktree" &&
+			flag !== "--worktree-base" &&
+			flag !== "--worktree-source"
+		) {
 			return { error: `unknown flag ${flag}; ${USAGE}` };
 		}
-		const value = tokens[i + 1]?.text;
-		if (value === undefined || value.startsWith("--")) return { error: `${flag} needs a value; ${USAGE}` };
-		if (flag === "--model") parsed.model = value;
-		else if (flag === "--thinking") parsed.thinking = value;
-		else parsed.label = value;
-		i += 2;
+		const read = flagValue(text, next.end, flag);
+		if ("error" in read) return read;
+		if (flag === "--model") parsed.model = read.value;
+		else if (flag === "--thinking") parsed.thinking = read.value;
+		else if (flag === "--label") parsed.label = read.value;
+		else if (flag === "--cwd") parsed.cwd = read.value;
+		else if (flag === "--worktree") parsed.worktree = read.value;
+		else if (flag === "--worktree-base") parsed.worktree_base = read.value;
+		else parsed.worktree_source = read.value;
+		at = read.end;
 	}
-	parsed.task = text.slice(tokens[i]?.start ?? text.length).trim();
+	// The task is the rest of the text from its first word, untouched by flag parsing.
+	parsed.task = text.slice(word(text, at)?.start ?? text.length).trim();
 	if (parsed.task === "") return { error: `a task is required after the agent and flags; ${USAGE}` };
 	return { parsed };
 }
 
+/** `/delegate-resume`'s arguments: a delegation id, optional flags, then a verbatim task. */
+function parseResume(text: string): { request: ResumeRequest } | { error: string } {
+	const id = word(text, 0);
+	if (id === undefined) return { error: RESUME_USAGE };
+	if (id.text.startsWith("-")) return { error: `the first argument is the delegation id; ${RESUME_USAGE}` };
+	const request: ResumeRequest = { id: id.text, task: "" };
+	let at = id.end;
+	for (let next = word(text, at); next?.text.startsWith("-"); next = word(text, at)) {
+		const flag = next.text;
+		if (flag === "--auto-exit" || flag === "--no-auto-exit") {
+			request.autoExit = flag === "--auto-exit";
+			at = next.end;
+			continue;
+		}
+		if (flag !== "--model" && flag !== "--thinking") return { error: `unknown flag ${flag}; ${RESUME_USAGE}` };
+		const read = flagValue(text, next.end, flag, RESUME_USAGE);
+		if ("error" in read) return read;
+		if (flag === "--model") request.model = read.value;
+		else request.thinking = read.value;
+		at = read.end;
+	}
+	request.task = text.slice(word(text, at)?.start ?? text.length).trim();
+	if (request.task === "") return { error: `a task is required after the id and flags; ${RESUME_USAGE}` };
+	return { request };
+}
+
 /** Why `value` is not a usable model, or undefined when it is. */
 function modelProblem(value: string, registry: ModelRegistry): string | undefined {
 	const slash = value.indexOf("/");
@@ -255,15 +403,17 @@ function modelProblem(value: string, registry: ModelRegistry): string | undefine
  * `modelProblem` and has no active mark wins; the rest are returned as skipped.
  * A paid candidate on a provider with a quota check is read first, and
  * skipped when its quota is used up. Refuses, listing every candidate, when
- * none is left.
+ * none is left. `preferred` replaces the agent's own list when there is no
+ * explicit model, as a resume does.
  */
 async function chooseModel(
 	explicit: string | undefined,
 	agent: Agent,
 	models: ModelRegistry,
 	proactive: Proactive,
+	preferred: readonly string[] = [agent.model, ...agent.fallback],
 ): Promise<{ model: string; skipped: Skipped[]; notices: string[]; rest: string[] }> {
-	const candidates = explicit !== undefined ? [explicit] : [agent.model, ...agent.fallback];
+	const candidates = explicit !== undefined ? [explicit] : [...preferred];
 	const skipped: Skipped[] = [];
 	const notices: string[] = [];
 	for (const model of candidates) {
@@ -352,7 +502,7 @@ function delegateVisible(options: { selectedTools: string[]; hiddenTools: string
 /** The `delegate` tool's description: what delegation does, and the roster as it stands. */
 function toolDescription(agents: readonly Agent[]): string {
 	const intro =
-		"Hand a self-contained task to a delegate Pi session in a background tmux window, so it works while you do not. Each call starts the delegation at once; the delegate runs in this session's working directory and agent root and reports back later as one message. While it runs, keep working or end your turn: its result starts your next turn on its own. Do not poll delegation_status or send a blocking mail request merely to wait for the result; send a substantive follow-up only when you have something to add or ask. Use it when the work is self-contained and you would rather keep your own context for it.";
+		"Hand a self-contained task to a delegate Pi session in a background tmux window, so it works while you do not. Each call starts the delegation at once; the delegate runs in this session's working directory, or the cwd given, with this session's agent root, and reports back later as one message. While it runs, keep working or end your turn: its result starts your next turn on its own. Do not poll delegation_status or send a blocking mail request merely to wait for the result; send a substantive follow-up only when you have something to add or ask. Use it when the work is self-contained and you would rather keep your own context for it.";
 	if (agents.length === 0) {
 		return `${intro}\n\nNo agents are defined yet. Add ${join(
 			getAgentDir(),
@@ -373,7 +523,8 @@ function toolDescription(agents: readonly Agent[]): string {
 				}${agent.tools.length > 0 ? `, tools: ${agent.tools.join("/")}` : ""})`,
 		),
 		"",
-		"`model` and `thinking` override the agent's defaults for this call; an unknown value is refused with close matches. `label` names the delegate's window and session; give one that says what the task is. `delegation_status` reports a delegation, and `delegation_close` ends one.",
+		"`cwd` runs the delegate in another existing directory. Alternatively, `worktree` creates a new local branch and checkout from this repository's committed HEAD, or `worktree_source` selects another existing Git checkout; `worktree_base` selects a commit in that source. Source dirt is reported but not copied. `cwd` and `worktree` are mutually exclusive, and source/base require worktree.",
+		"`model` and `thinking` override the agent's defaults for this call; an unknown value is refused with close matches. `label` names the delegate's window and session; give one that says what the task is. `delegation_status` reports a delegation, and `delegation_close` ends one. `delegation_resume` continues an exited delegate in its own session with a follow-up task, for work that needs the context it already built.",
 		"`auto_exit` (default the agent's, normally true) closes the delegate's window once it finishes. Set it false when you mean to keep talking to the delegate by mail after its result; the user can also keep a window open by typing in it.",
 		"",
 		"Writing the task: the delegate sees nothing of this session, so the task must stand alone. State the question, the decision its answer feeds, what is already known or ruled out, and the files or paths to start from. When the work produces a report, name the path to write it to and ask for the conclusion back, not the contents.",
@@ -464,39 +615,65 @@ export default function delegate(
 			rest,
 			thinking,
 			label: request.label,
+			cwd: request.cwd,
+			worktree: request.worktree,
+			worktree_base: request.worktree_base,
+			worktree_source: request.worktree_source,
 			autoExit: request.autoExit ?? agent.autoExit,
 			task: request.task,
 		};
 	}
 
-	/** The launch order of the spec: task, argv, env, listeners, window, record. */
-	async function launch(start: Start, ctx: ExtensionContext): Promise<Launched> {
-		if (!tmux.insideTmux()) throw new Error(NOT_IN_TMUX);
-
-		// The task goes on disk before the window exists: the delegate finds it
-		// at session start without a handshake, and a window that fails leaves
-		// mail that is reported rather than cleaned up.
-		const id = randomUUID();
-		const sent: SendPayload = { to: id, body: start.task };
+	/** Write the task to the delegate's inbox and return its request id; the delegate finds it at session start. */
+	function sendTask(to: string, task: string): string {
+		const sent: SendPayload = { to, body: task };
 		pi.events.emit(SEND, sent);
-		if (typeof sent.error === "string") throw new Error(`could not send the task to ${id}: ${sent.error}`);
-		if (sent.envelope === undefined) {
+		if (typeof sent.error === "string") throw new Error(`could not send the task to ${to}: ${sent.error}`);
+		if (sent.envelope === undefined)
 			throw new Error(
-				`needs a provider of message:* to send the task; install a mailbox extension (for example pi-session-mail)`,
+				"needs a provider of message:* to send the task; install a mailbox extension (for example pi-session-mail)",
 			);
-		}
 		const requestId = sent.envelope.id;
-		if (typeof requestId !== "string") throw new Error(`the message:send provider wrote no request id for ${id}`);
+		if (typeof requestId !== "string") throw new Error(`the message:send provider wrote no request id for ${to}`);
+		return requestId;
+	}
 
+	/**
+	 * Build the delegate's command line and environment, emit `session:launch`
+	 * and open its window; returns the window id. A launch and a resume share
+	 * it and differ only in `session`, the arguments that choose the session:
+	 * `--session-id <id> --name <name>` for a new one, `--session <path>` to reopen.
+	 */
+	async function openChild(input: {
+		id: string;
+		name: string;
+		session: string[];
+		workspace: Workspace;
+		trusted: boolean;
+		cwd: string;
+		sessionDir: string;
+		start: ChildStart;
+		/** The tool call that started this launch or resume; undefined from a command. */
+		toolCallId: string | undefined;
+		ctx: ExtensionContext;
+		onWindowOpened?: () => void;
+	}): Promise<string> {
+		const { id, name, session, workspace, trusted, cwd, sessionDir, start, toolCallId, ctx, onWindowOpened } = input;
 		const parent = ctx.sessionManager.getSessionId();
-		const name = delegateName(start.agent.name, id, start.label);
-		const prompt = writePromptFile(`${start.agent.prompt}\n\n${FINAL_LINE}\n\n${parentTrust(parent)}`);
+		const managedContext =
+			workspace.mode === "managed"
+				? `\n\nYour managed worktree is ${workspace.cwd}, branch ${workspace.createdBranch}, based on commit ${workspace.baseCommit}.`
+				: workspace.mode === "existing"
+					? `\n\nThe session that started you chose your working directory: ${workspace.cwd}`
+					: "";
+		const prompt = writePromptFile(`${start.agent.prompt}\n\n${FINAL_LINE}\n\n${parentTrust(parent)}${managedContext}`);
 		const argv = [
 			...parentCommand(),
-			"--session-id",
-			id,
-			"--name",
-			name,
+			...session,
+			// Always explicit, so a permissive global default cannot trust what the parent does not.
+			trusted ? "--approve" : "--no-approve",
+			"--session-dir",
+			sessionDir,
 			"--model",
 			start.model,
 			"--thinking",
@@ -516,20 +693,52 @@ export default function delegate(
 			PI_UNATTENDED: "1",
 		};
 		if (start.rest.length > 0) env[FALLBACK_ENV] = start.rest.join(",");
-		const sessionDir = process.env[SESSION_DIR_ENV];
-		if (sessionDir !== undefined && sessionDir !== "") env[SESSION_DIR_ENV] = sessionDir;
+		// Pi ranks `--session-dir` above this variable, so it cannot move the child's storage.
+		const envSessionDir = process.env[SESSION_DIR_ENV];
+		if (envSessionDir !== undefined && envSessionDir !== "") env[SESSION_DIR_ENV] = envSessionDir;
 		// Listeners may only append to `args` and add to `env`; there is no veto.
-		const payload: LaunchPayload = { args: argv, env, agent: start.agent.name };
+		const payload: LaunchPayload = { args: argv, env, agent: start.agent.name, cwd, toolCallId };
 		pi.events.emit(LAUNCH, payload);
-
-		const windowName = name;
 		let windowId: string;
 		try {
-			windowId = await tmux.openWindow({ name: windowName, cwd: ctx.cwd, argv: payload.args, env: payload.env });
+			windowId = await tmux.openWindow({ name, cwd, argv: payload.args, env: payload.env });
+			onWindowOpened?.();
 		} catch (err) {
-			throw new Error(`could not open window ${windowName} for ${id}: ${(err as Error).message}`);
+			if (err instanceof WindowOpenError) {
+				throw new WindowOpenError(`could not open window ${name} for ${id}: ${err.message}`, err.certainty);
+			}
+			throw new WindowOpenError(`could not open window ${name} for ${id}: ${(err as Error).message}`, "unknown");
 		}
+		return windowId;
+	}
 
+	async function launchWindow(input: {
+		id: string;
+		requestId: string;
+		workspace: Workspace;
+		trusted: boolean;
+		cwd: string;
+		sessionDir: string;
+		start: Start;
+		toolCallId: string | undefined;
+		ctx: ExtensionContext;
+		onWindowOpened: () => void;
+	}): Promise<Launched> {
+		const { id, requestId, workspace, trusted, cwd, sessionDir, start, toolCallId, ctx, onWindowOpened } = input;
+		const name = delegateName(start.agent.name, id, start.label);
+		const windowId = await openChild({
+			id,
+			name,
+			session: ["--session-id", id, "--name", name],
+			workspace,
+			trusted,
+			cwd,
+			sessionDir,
+			start,
+			toolCallId,
+			ctx,
+			onWindowOpened,
+		});
 		// No task text in the record: the request copy in `sent/` has it.
 		results.recordStart(
 			{
@@ -539,18 +748,233 @@ export default function delegate(
 				thinking: start.thinking,
 				name,
 				windowId,
-				windowName,
+				windowName: name,
 				requestId,
 				autoExit: start.autoExit,
+				cwd,
+				sessionDir,
+				workspace,
 			},
 			ctx,
 		);
 		tracking.startPolling();
-		return { id, name, windowId, windowName, requestId };
+		return { id, name, windowId, windowName: name, requestId, cwd, sessionDir, workspace };
+	}
+
+	async function launch(
+		start: Start,
+		ctx: ExtensionContext,
+		signal?: AbortSignal,
+		toolCallId?: string,
+	): Promise<Launched> {
+		if (!tmux.insideTmux()) throw new Error(NOT_IN_TMUX);
+		const sessionDir = ctx.sessionManager.getSessionDir();
+		if (!isAbsolute(sessionDir))
+			throw new Error(
+				`the parent's session directory ${JSON.stringify(sessionDir)} is not an absolute path; start Pi with an absolute --session-dir`,
+			);
+		const cwdOption = normalizeWorkspaceValue(start.cwd, "cwd");
+		const worktreeOption = normalizeWorkspaceValue(start.worktree, "worktree");
+		const baseOption = normalizeWorkspaceValue(start.worktree_base, "worktree_base");
+		const sourceOption = normalizeWorkspaceValue(start.worktree_source, "worktree_source");
+		if (sourceOption !== undefined && worktreeOption === undefined)
+			throw new Error("worktree_source requires worktree");
+		if (baseOption !== undefined && worktreeOption === undefined) throw new Error("worktree_base requires worktree");
+		if (cwdOption !== undefined && worktreeOption !== undefined)
+			throw new Error("cwd and worktree are mutually exclusive; name only one");
+		const signals = [signal, ctx.signal].filter((item): item is AbortSignal => item !== undefined);
+		const combined = signals.length ? AbortSignal.any(signals) : undefined;
+		let plan: WorktreePlan | undefined;
+		let directory: Workspace | undefined;
+		let trusted: boolean;
+		let revalidateTrust: (() => void) | undefined;
+		if (worktreeOption !== undefined) {
+			plan = await prepareWorktree(
+				{
+					worktree: worktreeOption,
+					...(baseOption === undefined ? {} : { worktree_base: baseOption }),
+					...(sourceOption === undefined ? {} : { worktree_source: sourceOption }),
+				},
+				ctx,
+				getAgentDir(),
+			);
+			if (combined?.aborted) throw new Error("the launch was aborted");
+			const trust = await trustPlannedWorktree(plan, ctx, getAgentDir(), combined);
+			if (combined?.aborted) throw new Error("the launch was aborted");
+			trusted = trust.trusted;
+			revalidateTrust = trust.revalidate;
+			plan.trusted = trusted;
+		} else {
+			const prepared = await prepareDirectory({ cwd: cwdOption, signal }, ctx, getAgentDir());
+			directory = prepared.workspace;
+			trusted = prepared.trusted;
+		}
+		const id = randomUUID();
+		const parentId = ctx.sessionManager.getSessionId();
+		let attempt: WorkspaceAttempt | undefined;
+		let managed: Extract<Workspace, { mode: "managed" }> | undefined;
+		let windowOpened = false;
+		const run = async (): Promise<Launched> => {
+			if (plan !== undefined) {
+				revalidate(plan);
+				revalidateTrust?.();
+				attempt = {
+					kind: "workspace-attempt",
+					id,
+					parentId,
+					agent: start.agent.name,
+					model: start.model,
+					thinking: start.thinking,
+					...(start.label === undefined ? {} : { name: start.label }),
+					sessionDir,
+					plan,
+					attempt: { phase: "planned", resources: { kind: "none" } },
+				};
+				results.recordAttempt(attempt, ctx);
+				const created = createWorktree(plan);
+				if (!("workspace" in created)) {
+					const recovery = recoveryCommands(plan, created.resources);
+					attempt = {
+						...attempt,
+						attempt:
+							created.resources.kind === "none"
+								? { phase: "rolled-back", resources: { kind: "none" }, cause: created.cause }
+								: { phase: "retained", resources: created.resources, cause: created.cause, recovery },
+					};
+					results.recordAttempt(attempt, ctx);
+					throw new Error(
+						`worktree launch ${id} from ${plan.sourceCwd} failed at ${plan.destination} (${plan.branch}): ${created.cause}; ${resourceLine(created.resources)}${recovery.length ? `; recovery: ${recovery.join("; ")}` : created.resources.kind === "worktree" ? "; inspect and preserve its contents before any cleanup" : ""}`,
+					);
+				}
+				managed = created.workspace;
+				attempt = {
+					...attempt,
+					attempt: {
+						phase: "created",
+						resources: { kind: "worktree", cwd: managed.cwd, branch: managed.createdBranch, head: managed.baseCommit },
+					},
+				};
+				results.recordAttempt(attempt, ctx);
+			}
+			let workspace: Workspace;
+			if (managed !== undefined) workspace = managed;
+			else if (directory !== undefined) workspace = directory;
+			else throw new Error("workspace preparation did not produce a launch directory");
+			// The task goes on disk before the window exists: the delegate finds it
+			// at session start without a handshake, and a window that fails leaves
+			// mail that is reported rather than cleaned up.
+			const requestId = sendTask(id, start.task);
+			if (attempt !== undefined) {
+				attempt = { ...attempt, requestId };
+				results.recordAttempt(attempt, ctx);
+			}
+			return launchWindow({
+				id,
+				requestId,
+				workspace,
+				trusted,
+				cwd: workspace.cwd,
+				sessionDir,
+				start,
+				toolCallId,
+				ctx,
+				onWindowOpened: () => {
+					windowOpened = true;
+				},
+			});
+		};
+		const runWithRollback = async (): Promise<Launched> => {
+			try {
+				return await run();
+			} catch (error) {
+				if (attempt !== undefined && managed !== undefined) {
+					const cause = (error as Error).message;
+					if (windowOpened || (error instanceof WindowOpenError && error.certainty === "unknown")) {
+						attempt = {
+							...attempt,
+							attempt: {
+								phase: "retained",
+								resources: {
+									kind: "worktree",
+									cwd: managed.cwd,
+									branch: managed.createdBranch,
+									head: managed.baseCommit,
+								},
+								cause,
+								recovery: [],
+							},
+						};
+					} else {
+						const rollbackPlan = plan;
+						if (rollbackPlan === undefined) throw error;
+						const rolled = rollbackWorktree(rollbackPlan, managed);
+						attempt =
+							rolled.kind === "rolled-back"
+								? { ...attempt, attempt: { phase: "rolled-back", resources: { kind: "none" }, cause } }
+								: {
+										...attempt,
+										attempt: {
+											phase: "retained",
+											resources: rolled.resources,
+											cause: `${cause}; ${rolled.reason}`,
+											recovery: recoveryCommands(rollbackPlan, rolled.resources),
+										},
+									};
+					}
+					results.recordAttempt(attempt, ctx);
+					const state = attempt.attempt;
+					const recovery =
+						state.phase !== "retained"
+							? ""
+							: state.recovery.length > 0
+								? `; recovery: ${state.recovery.join("; ")}`
+								: state.resources.kind === "worktree"
+									? "; inspect and preserve its contents before any cleanup"
+									: "";
+					throw new Error(
+						`worktree launch ${id} from ${managed.sourceCwd} at ${managed.cwd} (${managed.createdBranch}) failed: ${cause}; outcome ${state.phase}${recovery}`,
+						{ cause: error },
+					);
+				}
+				throw error;
+			}
+		};
+		if (plan === undefined) return runWithRollback();
+		return inQueue(plan.source.commonDir, combined, runWithRollback);
 	}
 
+	const resumer = createResume({
+		results,
+		tmux,
+		delegateSchema: DelegateSchema,
+		notInTmux: NOT_IN_TMUX,
+		startPolling: tracking.startPolling,
+		roster: rosterFor,
+		chooseModel: (explicit, agent, models, preferred) => chooseModel(explicit, agent, models, proactive, preferred),
+		thinkingProblem,
+		prepareDirectory: (cwd, ctx, signal) => prepareDirectory({ cwd, signal }, ctx, getAgentDir()),
+		sendTask,
+		open: ({ id, name, sessionPath, workspace, trusted, cwd, sessionDir, start, toolCallId, ctx }) =>
+			openChild({
+				id,
+				name,
+				session: ["--session", sessionPath],
+				workspace,
+				trusted,
+				cwd,
+				sessionDir,
+				start,
+				toolCallId,
+				ctx,
+			}),
+	});
+
+	/** Where a selected directory put the delegate, for the start text; inherited starts stay compact. */
+	const placedIn = (launched: Launched): string =>
+		launched.workspace.mode !== "inherited" ? ` in ${launched.cwd}` : "";
+
 	const started = (launched: Launched, start: Start): string =>
-		`delegate: ${start.agent.name} ${launched.id} started in window ${launched.windowName}${start.skipped.length > 0 ? `. ${fallbackNote(start)}` : ""}${start.notices.map((line) => `. ${line}`).join("")}`;
+		`delegate: ${start.agent.name} ${launched.id} started in window ${launched.windowName}${placedIn(launched)}${launched.workspace.mode === "managed" ? `. Branch ${launched.workspace.createdBranch} starts at ${launched.workspace.baseCommit}. ${dirtyNotice(launched.workspace.sourceDirty)}` : ""}${start.skipped.length > 0 ? `. ${fallbackNote(start)}` : ""}${start.notices.map((line) => `. ${line}`).join("")}`;
 
 	async function command(input: string, ctx: ExtensionContext): Promise<void> {
 		const fail = (message: string) => ctx.ui.notify(`delegate: ${message}`, "error");
@@ -560,7 +984,17 @@ export default function delegate(
 			return;
 		}
 		try {
-			const start = await validate(outcome.parsed, rosterFor(ctx), ctx.modelRegistry);
+			const cwd = normalizeWorkspaceValue(outcome.parsed.cwd, "--cwd");
+			const worktree_source = normalizeWorkspaceValue(outcome.parsed.worktree_source, "--worktree-source");
+			const worktree_base = normalizeWorkspaceValue(outcome.parsed.worktree_base, "--worktree-base");
+			const worktree = normalizeWorkspaceValue(outcome.parsed.worktree, "--worktree");
+			if (worktree_source !== undefined && worktree === undefined)
+				throw new Error("--worktree-source requires --worktree");
+			const start = await validate(
+				{ ...outcome.parsed, cwd, worktree, worktree_base, worktree_source },
+				rosterFor(ctx),
+				ctx.modelRegistry,
+			);
 			const launched = await launch(start, ctx);
 			ctx.ui.notify(started(launched, start), "info");
 		} catch (err) {
@@ -568,6 +1002,19 @@ export default function delegate(
 		}
 	}
 
+	async function resumeCommand(input: string, ctx: ExtensionContext): Promise<void> {
+		const outcome = parseResume(input);
+		if ("error" in outcome) {
+			ctx.ui.notify(`delegate: ${outcome.error}`, "error");
+			return;
+		}
+		try {
+			ctx.ui.notify(startedLine(await resumer.resume(outcome.request, ctx)), "info");
+		} catch (err) {
+			ctx.ui.notify(`delegate: ${(err as Error).message}`, "error");
+		}
+	}
+
 	/** The roster description last registered, so unchanged metadata is not registered again. */
 	let registeredDescription: string | undefined;
 
@@ -589,6 +1036,29 @@ export default function delegate(
 					description: `A short name for this delegation (letters, digits, _ or -, at most ${LABEL_MAX}), such as roster-research. Its session and tmux window are named <agent>-<label>; without it, <agent>-<first 8 id characters>.`,
 				}),
 			),
+			cwd: Type.Optional(
+				Type.Union([Type.String(), Type.Null()], {
+					description:
+						"An existing directory to run the delegate in: absolute, relative to this session's working directory, or starting with ~/. Omit to run in this session's working directory. The directory is used as it is; nothing is created or cleaned up. Mutually exclusive with worktree.",
+				}),
+			),
+			worktree: Type.Optional(
+				Type.Union([Type.String(), Type.Null()], {
+					description:
+						"Create a new managed worktree and local branch with this literal branch name, from this repository's committed HEAD or explicit worktree_base. Source dirt is not copied. Mutually exclusive with cwd.",
+				}),
+			),
+			worktree_source: Type.Optional(
+				Type.Union([Type.String(), Type.Null()], {
+					description:
+						"Existing Git checkout to create from; relative to this session or starting with ~/. Requires worktree.",
+				}),
+			),
+			worktree_base: Type.Optional(
+				Type.Union([Type.String(), Type.Null()], {
+					description: "Local commit-ish to create the branch from; requires worktree. No fetch is performed.",
+				}),
+			),
 			auto_exit: Type.Optional(
 				Type.Boolean({
 					description:
@@ -600,9 +1070,9 @@ export default function delegate(
 		renderCall: renderDelegateCall,
 		renderResult: renderDelegateResult,
 		// Opens a new window each call and removes nothing. Open world: the delegate calls a remote model and runs its agent's tools unattended.
-		annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+		annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
 		async execute(
-			_toolCallId: string,
+			toolCallId: string,
 			params: {
 				agent: string;
 				task: string;
@@ -610,30 +1080,42 @@ export default function delegate(
 				thinking?: string | null;
 				label?: string | null;
 				auto_exit?: boolean | null;
+				cwd?: unknown;
+				worktree?: unknown;
+				worktree_base?: unknown;
+				worktree_source?: unknown;
 			},
-			_signal: unknown,
+			signal: AbortSignal | undefined,
 			_onUpdate: unknown,
 			ctx: ExtensionContext,
 		) {
 			if (!tmux.insideTmux()) throw new Error(NOT_IN_TMUX);
 			// Some models fill every optional field with null or the string "null"; both mean unset.
 			const given = (value: string | null | undefined) => (value == null || value === "null" ? undefined : value);
+			const cwd = normalizeWorkspaceValue(params.cwd, "cwd");
+			const worktree = normalizeWorkspaceValue(params.worktree, "worktree");
+			const worktree_base = normalizeWorkspaceValue(params.worktree_base, "worktree_base");
+			const worktree_source = normalizeWorkspaceValue(params.worktree_source, "worktree_source");
 			const start = await validate(
 				{
 					agent: params.agent,
 					model: given(params.model),
 					thinking: given(params.thinking),
 					label: given(params.label),
+					cwd,
+					worktree,
+					worktree_base,
+					worktree_source,
 					autoExit: typeof params.auto_exit === "boolean" ? params.auto_exit : undefined,
 					task: params.task ?? "",
 				},
 				rosterFor(ctx),
 				ctx.modelRegistry,
 			);
-			const launched = await launch(start, ctx);
+			const launched = await launch(start, ctx, signal, toolCallId);
 			ctx.ui.notify(started(launched, start), "info");
 			return toolResult(
-				`Started delegation ${launched.id}: ${start.agent.name} (${start.model}, thinking ${start.thinking}) in window ${launched.windowName}. It runs in the background, and its result arrives as a message that starts your next turn on its own; delegation_close ends it.${start.skipped.length > 0 ? ` ${fallbackNote(start)}` : ""}${start.notices.map((line) => ` ${line}`).join("")}`,
+				`Started delegation ${launched.id}: ${start.agent.name} (${start.model}, thinking ${start.thinking}) in window ${launched.windowName}${placedIn(launched)}.${launched.workspace.mode === "managed" ? ` Branch ${launched.workspace.createdBranch} starts at ${launched.workspace.baseCommit}. ${dirtyNotice(launched.workspace.sourceDirty)}` : ""} It runs in the background, and its result arrives as a message that starts your next turn on its own; delegation_close ends it.${start.skipped.length > 0 ? ` ${fallbackNote(start)}` : ""}${start.notices.map((line) => ` ${line}`).join("")}`,
 				{
 					outcome: "started",
 					id: launched.id,
@@ -645,6 +1127,9 @@ export default function delegate(
 					autoExit: start.autoExit,
 					windowId: launched.windowId,
 					windowName: launched.windowName,
+					cwd: launched.cwd,
+					sessionDir: launched.sessionDir,
+					workspace: launched.workspace,
 				},
 			);
 		},
@@ -704,6 +1189,26 @@ export default function delegate(
 		handler: command,
 	});
 
+	/** Delegation ids, flags, model ids and thinking levels, at the cursor's token. */
+	function resumeCompletions(prefix: string): { value: string; label: string }[] | null {
+		const partial = /(?:^|\s)(\S*)$/.exec(prefix)?.[1] ?? "";
+		const head = prefix.slice(0, prefix.length - partial.length);
+		const tokens = head.trim() === "" ? [] : head.trim().split(/\s+/);
+		const previous = tokens[tokens.length - 1];
+		let values: readonly string[] = RESUME_FLAGS;
+		if (tokens.length === 0) values = resumableIds(results);
+		else if (previous === "--model") values = modelIds(registry);
+		else if (previous === "--thinking") values = THINKING_LEVELS;
+		const hits = values.filter((value) => value.startsWith(partial));
+		return hits.length > 0 ? hits.map((value) => ({ value: head + value, label: value })) : null;
+	}
+
+	pi.registerCommand("delegate-resume", {
+		description: `Reopen an exited delegate's session in a new window with a follow-up task: ${RESUME_USAGE}`,
+		getArgumentCompletions: resumeCompletions,
+		handler: resumeCommand,
+	});
+
 	pi.registerCommand("delegate-clear", {
 		description: "Clear usage-limit marks: all, a provider, or a provider/model",
 		getArgumentCompletions: (prefix: string) => {
@@ -734,4 +1239,5 @@ export default function delegate(
 
 	registerDelegate(toolDescription(currentRoster().agents));
 	tracking.registerTools();
+	pi.registerTool(resumer.tool() as never);
 }