pi-squire 0.9.4 → 0.10.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
@@ -23,7 +24,8 @@
 // The model gets three 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.
@@ -36,7 +38,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 +51,27 @@ 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 { 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 +120,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 +146,31 @@ 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>";
 
 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 };
+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 +183,28 @@ 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 };
 /** 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,31 +264,74 @@ 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): { 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 };
 }
@@ -352,7 +453,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,6 +474,7 @@ function toolDescription(agents: readonly Agent[]): string {
 				}${agent.tools.length > 0 ? `, tools: ${agent.tools.join("/")}` : ""})`,
 		),
 		"",
+		"`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.",
 		"`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.",
 		"",
@@ -464,39 +566,46 @@ 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 };
-		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) {
-			throw new Error(
-				`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}`);
-
+	async function launchWindow(input: {
+		id: string;
+		requestId: string;
+		workspace: Workspace;
+		trusted: boolean;
+		cwd: string;
+		sessionDir: string;
+		start: Start;
+		ctx: ExtensionContext;
+		onWindowOpened: () => void;
+	}): Promise<Launched> {
+		const { id, requestId, workspace, trusted, cwd, sessionDir, start, 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,
+			// 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 +625,22 @@ 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 };
 		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");
 		}
-
 		// No task text in the record: the request copy in `sent/` has it.
 		results.recordStart(
 			{
@@ -539,18 +650,209 @@ 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): 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 sent: SendPayload = { to: id, body: start.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)
+				throw new Error(
+					"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 (attempt !== undefined) {
+				attempt = { ...attempt, requestId };
+				results.recordAttempt(attempt, ctx);
+			}
+			return launchWindow({
+				id,
+				requestId,
+				workspace,
+				trusted,
+				cwd: workspace.cwd,
+				sessionDir,
+				start,
+				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);
+	}
+
+	/** 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 +862,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) {
@@ -589,6 +901,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,7 +935,7 @@ 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,
 			params: {
@@ -610,30 +945,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);
 			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 +992,9 @@ export default function delegate(
 					autoExit: start.autoExit,
 					windowId: launched.windowId,
 					windowName: launched.windowName,
+					cwd: launched.cwd,
+					sessionDir: launched.sessionDir,
+					workspace: launched.workspace,
 				},
 			);
 		},