pi-squire 0.19.1 → 0.20.1

package/CHANGELOG.md

@@ -6,6 +6,33 @@ follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.20.1] - 2026-11-02
+
+### Changed
+
+- `delegation_fork` warns when its effective model differs from the source's
+  last model: copied context will be written to a new cache, with an approximate
+  token count when source usage is available. The model parameter and README
+  explain the cost; same-model forks retain their cache behavior. New fork tests
+  cover changed/same models, effective model locks and missing or invalid usage.
+
+## [0.20.0] - 2026-11-02
+
+### Added
+
+- `delegation_fork({ id, task })` starts a new delegation from a direct child's
+  session context using `pi --fork`, leaving the original session and window
+  untouched. It runs in the child's folder or a new managed worktree, inherits
+  resume-style model/thinking/auto-exit defaults, and reapplies current roster,
+  nesting, capacity and trust checks. New records, status and results carry
+  `forkedFrom`; replies use the new session's own address. The metadata budget
+  test increases from 10,000 to 12,000 characters to cover the fifth tool.
+  Managed forks report their cwd, branch, base and uncopied changes, and their
+  prompt directs them away from the original checkout; non-isolated forks warn
+  about sharing a folder with a running source. Dashboard details show the
+  source id, foreign callers get an explicit direct-parent refusal, and the
+  fork tool declares its destructive-operation hint.
+
 ## [0.19.1] - 2026-11-02
 
 ### Removed
@@ -1094,7 +1121,9 @@ author's dotfiles; the changes below are against that copy.
 
 - The published file list includes `child.ts`, which `index.ts` imports.
 
-[Unreleased]: https://github.com/gvanderclay/pi-squire/compare/v0.19.1...HEAD
+[Unreleased]: https://github.com/gvanderclay/pi-squire/compare/v0.20.1...HEAD
+[0.20.1]: https://github.com/gvanderclay/pi-squire/compare/v0.20.0...v0.20.1
+[0.20.0]: https://github.com/gvanderclay/pi-squire/compare/v0.19.1...v0.20.0
 [0.19.1]: https://github.com/gvanderclay/pi-squire/compare/v0.19.0...v0.19.1
 [0.19.0]: https://github.com/gvanderclay/pi-squire/compare/v0.18.4...v0.19.0
 [0.18.4]: https://github.com/gvanderclay/pi-squire/compare/v0.18.3...v0.18.4

package/README.md

@@ -175,7 +175,7 @@ scalars, quoted booleans, malformed lists and patterns) disable the agent with
 a path-specific warning. Unknown or unavailable names warn and cannot launch;
 known entries remain usable, and later roster changes apply normally.
 Below the limit the grant adds `delegate`,
-`delegation_status`, `delegation_close` and `delegation_resume` even with an
+`delegation_status`, `delegation_close`, `delegation_resume` and `delegation_fork` even with an
 explicit `tools` list. Merely listing those
 tools (including by pattern) does not opt in and produces
 a roster warning. At the depth limit they are inactive and not passed onward.
@@ -1021,7 +1021,7 @@ agent that uses a bundle, with the reason; agents without bundles are
 unaffected. (`$`, unlike `@`, may start a plain YAML value.)
 
 The delegation tools (`delegate`, `delegation_status`, `delegation_close`,
-`delegation_resume`) are removed from ordinary tool selections. An opted-in
+`delegation_resume`, `delegation_fork`) are removed from ordinary tool selections. An opted-in
 coordinator below `maxDepth` receives them automatically; a leaf has them
 inactive. Commands are still registered but cannot bypass admission. See the
 unreleased [nesting restrictions](#nested-delegation-unreleased).
@@ -1135,7 +1135,7 @@ agent's `auto_exit`.
 
 ## Tools
 
-The model gets four tools. They share the command's launch path and the
+The model gets five tools. They share the command's launch path and the
 session's delegation records. In a delegate they are active only for an
 opted-in coordinator below `maxDepth`; admission also checks every launch/resume.
 
@@ -1145,6 +1145,7 @@ opted-in coordinator below `maxDepth`; admission also checks every launch/resume
 | `delegation_status` | optional `id` | Reports each delegation as running, done, closed or closed without a result, with the window, the delegate's session and the result envelope's path. |
 | `delegation_close` | `id` | Explicitly fences and closes a descendant subtree using current verified windows. Returns per-member outcomes and complete/partial status; retains worktrees and branches. |
 | `delegation_resume` | `id`, `task`, optional `model`, `thinking` and `auto_exit` | Reopens an exited delegate's own session in a new window with a follow-up task, and returns the new delegation's id at once (see [Resuming a delegation](#resuming-a-delegation)). |
+| `delegation_fork` | `id`, `task`, optional `model`, `thinking`, `auto_exit`, `worktree` and `worktree_base` | Starts a new delegation from a copy of a direct child's context, leaving the original untouched (see [Forking a delegation](#forking-a-delegation)). |
 
 The `delegate` tool's description lists the current roster, one line per agent:
 its name and any display name, description, default model (or this session's)
@@ -1638,6 +1639,43 @@ and it resumes as the command does.
 - Not detected: a Pi process you opened yourself on the same session outside
   pi-squire's window. Close it before resuming.
 
+## Forking a delegation
+
+Call `delegation_fork({ id, task })` when new work needs a child's built context
+without continuing that child's session. It runs
+`pi --fork <child session file> --session-id <new id>` in a new tmux window.
+The source may still be running; its window, task and session file are untouched.
+Without `worktree`, both sessions share the working folder; the tool warns when
+the source is running and recommends `worktree` to isolate their file changes.
+Pi copies the source history available when the new process starts, not future
+messages. An older delegation in a resumed chain names that chain's shared
+session file, so it copies the session's current history rather than an old snapshot.
+
+The new session runs in the working folder from the source session's header.
+Pass `worktree: "<new branch>"` to create a managed worktree from that folder's
+checkout instead; `worktree_base` optionally selects a local commit-ish rather
+than its HEAD. Normal worktree trust, placement and rollback checks apply.
+This copies conversation context, not uncommitted checkout changes.
+The fork's launch prompt names the source folder and tells it to work only in
+the new worktree, where the source's uncommitted changes are absent.
+
+The tool returns the `delegate` result plus `forkedFrom`. The new delegation
+has its own session/mail address and window name, and receives the new task
+like a fresh delegate. Its result arrives through the normal `[delegate]`
+message; results and status name `forkedFrom`. Forking does not supersede the
+source or prevent further forks/resumes.
+
+Only the source's direct parent may fork it. The source session and working
+folder must exist, its agent must still be enabled, and current nesting grants,
+depth, capacity and trust checks apply. Copied history does not transfer
+ownership of the original child's descendants. Model, thinking and auto-exit
+default to the source's last settings with the same locks and fallbacks as a
+resume; the current roster supplies the prompt and tools. A different effective
+model re-reads the copied context without the source's cache; the result warns
+about the new cache write, estimating copied tokens when source usage is
+available. Keep the source's model unless the task needs another role.
+`session:launch` is emitted with the `delegation_fork` tool call id.
+
 ## Hooks
 
 The `js` block below is the contract's worked example, and
@@ -1660,7 +1698,7 @@ the window is open (see [Resuming a delegation](#resuming-a-delegation)).
 | `env` | the child's environment, as `KEY`/`value` pairs |
 | `agent` | the agent's name, as in `<agent dir>/agents/<name>.md` or `<cwd>/.pi/agents/<name>.md` (never its `display_name`); read it, do not change it |
 | `cwd` | the directory the window opens in, the parent's or the resolved `--cwd`; read it, do not change it |
-| `toolCallId` | the ID of the `delegate` or `delegation_resume` tool call that started the launch; absent when started from the `/delegate` or `/delegate-resume` command; read it, do not change it |
+| `toolCallId` | the ID of the `delegate`, `delegation_resume` or `delegation_fork` tool call that started the launch; absent when started from the `/delegate` or `/delegate-resume` command; read it, do not change it |
 | `parent` | Read-only direct parent session id. |
 | `root` | Read-only root session id; retained on resume. |
 | `depth` | Read-only numeric child depth, root = 0; retained on resume. |
@@ -1688,9 +1726,9 @@ environment into these arguments.
 
 `cwd`, the trust flag (`--approve` or `--no-approve`), `--session-dir` and the
 session choice (`--session-id` for a new delegate, `--session` for a [resumed](#resuming-a-delegation)
-one) are launch invariants that `pi-squire` chooses. The window opens in its own `cwd`,
+one, `--fork` with `--session-id` for a [fork](#forking-a-delegation)) are launch invariants that `pi-squire` chooses. The window opens in its own `cwd`,
 whatever a listener assigns to the payload. A listener must not add another
-trust flag, `--session-dir`, `--session` or `--session-id`, or a working-directory change to `args`, since
+trust flag, `--session-dir`, `--session`, `--fork` or `--session-id`, or a working-directory change to `args`, since
 that would launch a child whose trust or session storage the parent did not
 choose and cannot find; append only unrelated settings.
 
@@ -1965,7 +2003,7 @@ Other extensions may rely on:
   [Hooks](#hooks));
 - the `message:send`, `message:reply`, `message:inbound` and `message:scan` hooks, consumed as
   their sections document;
-- the `delegate`, `delegation_status`, `delegation_close` and `delegation_resume` tool names,
+- the `delegate`, `delegation_status`, `delegation_close`, `delegation_resume` and `delegation_fork` tool names,
   parameters, the recorded `workspace` shape and the `workspaceSnapshot`
   shape in results and status;
 - the `/delegate` and `/delegate-resume` syntax and flags, and their

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-squire",
-	"version": "0.19.1",
+	"version": "0.20.1",
 	"description": "Starts a delegate Pi session in a background tmux window, sends it the task over message:*, and shows the parent its result",
 	"keywords": [
 		"pi-package",

package/src/agents.ts

@@ -174,7 +174,7 @@ function warnDelegationTools(path: string, nested: unknown, tools: string[] | un
 	if (nested === true || (Array.isArray(nested) && nested.length > 0)) return;
 	if (
 		tools?.some((name) =>
-			["delegate", "delegation_status", "delegation_close", "delegation_resume"].some((tool) =>
+			["delegate", "delegation_status", "delegation_close", "delegation_resume", "delegation_fork"].some((tool) =>
 				toolMatches(name, tool),
 			),
 		)

package/src/fork.ts

@@ -0,0 +1,183 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import { disabledProblem, THINKING_LEVELS } from "./agents.ts";
+import { dirtyNotice } from "./render.ts";
+import { finishedModel, sessionInputTokens } from "./result-sessions.ts";
+import { deriveState, isStarted, type StartedRecorded } from "./results.ts";
+import type { ResumeDeps, Resumed } from "./resume.ts";
+import { sessionFor, settleModel } from "./resume-checks.ts";
+import { listWindows, type ToolDef, toolResult, windowState } from "./tracking.ts";
+import { assertChildAuthority, recordedIdentity } from "./tree-view.ts";
+
+export type ForkSource = {
+	id: string;
+	sessionPath: string;
+	sessionDir: string;
+	rootPlacement: string;
+	sourceCwd: string;
+};
+type Forked = Omit<Resumed, "resumedFrom" | "fallbackNote">;
+type ForkRequest = {
+	id: string;
+	task: string;
+	model?: string | null;
+	thinking?: string | null;
+	auto_exit?: boolean | null;
+	worktree?: string | null;
+	worktree_base?: string | null;
+};
+type ForkStart = Awaited<ReturnType<ResumeDeps["chooseModel"]>> & {
+	agent: ReturnType<ResumeDeps["roster"]>["agents"][number];
+	thinking: string;
+	autoExit: boolean;
+	task: string;
+	cwd: string;
+	worktree?: string;
+	worktree_base?: string;
+};
+type ForkDeps = Pick<
+	ResumeDeps,
+	"results" | "tmux" | "roster" | "parentDefaults" | "chooseModel" | "thinkingProblem" | "delegateSchema"
+> & {
+	authorize(id: string, ctx: ExtensionContext): void;
+	admit(agent: string, ctx: ExtensionContext): void;
+	launch(
+		start: ForkStart,
+		source: ForkSource,
+		ctx: ExtensionContext,
+		signal: AbortSignal | undefined,
+		toolCallId: string,
+	): Promise<Forked>;
+};
+
+function given(value: string | null | undefined): string | undefined {
+	return value == null || value === "null" ? undefined : value;
+}
+
+function sourceRecord(deps: ForkDeps, id: string, ctx: ExtensionContext): StartedRecorded {
+	deps.authorize(id, ctx);
+	const record = deps.results.find(id);
+	if (!record) throw new Error(`no delegation ${JSON.stringify(id)}`);
+	if (!isStarted(record)) throw new Error(`delegation ${id} is a workspace attempt, not a session to fork`);
+	assertChildAuthority(record, ctx, "fork");
+	deps.admit(record.agent, ctx);
+	deps.results.checkStorage(true);
+	return record;
+}
+
+function forkSource(record: StartedRecorded, session: ReturnType<typeof sessionFor>): ForkSource {
+	const own = recordedIdentity(record);
+	if (!own) throw new Error(`delegation ${record.id} has no original root placement identity; fork refused`);
+	return {
+		id: record.id,
+		sessionPath: session.path,
+		sessionDir: session.dir,
+		rootPlacement: own.rootPlacement,
+		sourceCwd: session.cwd,
+	};
+}
+
+function fallbackNote(chosen: Awaited<ReturnType<ResumeDeps["chooseModel"]>>): string {
+	return chosen.skipped.length
+		? ` Used fallback ${chosen.model} because ${chosen.skipped.map((item) => `${item.model} is ${item.why}`).join("; ")}.`
+		: "";
+}
+
+async function sharedFolderNotice(deps: ForkDeps, record: StartedRecorded, worktree?: string): Promise<string[]> {
+	if (worktree || deriveState(record, windowState(await listWindows(deps.tmux), record)) !== "running") return [];
+	return [`shares a working folder with running delegation ${record.id}; pass worktree to isolate`];
+}
+
+function modelNotice(record: StartedRecorded, sessionPath: string, model: string): string[] {
+	const sourceModel = finishedModel(sessionPath) ?? record.result?.finishedModel ?? record.model;
+	if (model === sourceModel) return [];
+	const tokens = sessionInputTokens(sessionPath);
+	const estimate = tokens === undefined ? "copied tokens" : `about ${Math.round(tokens / 1000)}k copied tokens`;
+	return [`${model} differs from the source's ${sourceModel}: ${estimate} will be written to a new cache.`];
+}
+
+function launchText(id: string, details: Forked, chosen: Awaited<ReturnType<ResumeDeps["chooseModel"]>>): string {
+	const workspace = details.workspace;
+	const managed =
+		workspace.mode === "managed"
+			? ` Branch ${workspace.createdBranch} starts at ${workspace.baseCommit}. ${dirtyNotice(workspace.sourceDirty)}`
+			: "";
+	return `Forked delegation ${id} as ${details.id} in window ${details.windowName} in ${details.cwd}.${managed} The original session is untouched. Its result arrives as a message that starts your next turn on its own; delegation_close ends it.${fallbackNote(chosen)}${details.notices.map((notice) => ` ${notice}`).join("")}`;
+}
+
+const modelParameter = Type.Optional(
+	Type.String({
+		description:
+			"provider/id; defaults to the source's last model. A different model re-reads the copied context without its cache; keep the source's model unless the task needs another role.",
+	}),
+);
+
+export function forkTool(deps: ForkDeps): ToolDef {
+	return {
+		name: "delegation_fork",
+		label: "Fork delegation",
+		description:
+			"Start a new direct child from a copy of an existing child's session context, with a new task, session id and window. The original child is untouched and may still be running. Runs in its working folder, or a new managed worktree from that folder's checkout. Results arrive as messages like other delegations.",
+		parameters: Type.Object({
+			id: Type.String({ description: "The direct child's delegation id whose context to copy." }),
+			task: Type.String(),
+			model: modelParameter,
+			thinking: Type.Optional(
+				Type.String({ description: `${THINKING_LEVELS.join(", ")}; defaults to the source's last level.` }),
+			),
+			auto_exit: Type.Optional(Type.Boolean({ description: "Defaults to the source delegation's setting." })),
+			worktree: Type.Optional(
+				Type.String({ description: "New branch for a managed worktree from the child's checkout." }),
+			),
+			worktree_base: Type.Optional(
+				Type.String({ description: "Local commit-ish; requires worktree. Defaults to the child's checkout HEAD." }),
+			),
+		}),
+		outputSchema: Type.Object({ ...deps.delegateSchema.properties, forkedFrom: Type.String() }),
+		annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+		async execute(
+			toolCallId: string,
+			params: ForkRequest,
+			signal: AbortSignal | undefined,
+			_onUpdate: unknown,
+			ctx: ExtensionContext,
+		): Promise<ReturnType<typeof toolResult>> {
+			if (!params.task?.trim()) throw new Error("a task is required");
+			const record = sourceRecord(deps, params.id, ctx);
+			const session = sessionFor(record, ctx, "forkable");
+			const roster = deps.roster(ctx);
+			const disabled = disabledProblem(roster, record.agent);
+			if (disabled) throw new Error(disabled);
+			const agent = roster.agents.find((item) => item.name === record.agent);
+			if (!agent) throw new Error(`agent ${JSON.stringify(record.agent)} is no longer in the roster`);
+			const { thinking, chosen } = await settleModel(
+				deps,
+				{ record, agent, session, request: { model: given(params.model), thinking: given(params.thinking) } },
+				ctx,
+			);
+			const source = forkSource(record, session);
+			chosen.notices.push(...modelNotice(record, session.path, chosen.model));
+			chosen.notices.push(...(await sharedFolderNotice(deps, record, given(params.worktree))));
+			const details = await deps.launch(
+				{
+					...chosen,
+					agent,
+					thinking,
+					autoExit: typeof params.auto_exit === "boolean" ? params.auto_exit : record.autoExit === true,
+					task: params.task,
+					cwd: session.cwd,
+					worktree: given(params.worktree),
+					worktree_base: given(params.worktree_base),
+				},
+				source,
+				ctx,
+				signal,
+				toolCallId,
+			);
+			const line = launchText(record.id, details, chosen);
+			ctx.ui.notify(`delegate: ${line}`, "info");
+			return toolResult(line, { outcome: "started", ...details, forkedFrom: record.id });
+		},
+	};
+}

package/src/identity.ts

@@ -8,7 +8,13 @@ import type { Agent, Roster } from "./agents.ts";
 import { readState, writeState } from "./local-state.ts";
 import { assertRootPlacement } from "./window-placement.ts";
 
-export const DELEGATION_TOOLS = ["delegate", "delegation_status", "delegation_close", "delegation_resume"] as const;
+export const DELEGATION_TOOLS = [
+	"delegate",
+	"delegation_status",
+	"delegation_close",
+	"delegation_resume",
+	"delegation_fork",
+] as const;
 export type Identity = {
 	parent: string;
 	root: string;

package/src/index.ts

@@ -24,7 +24,7 @@
 // An agent with no `model` or `thinking` runs
 // on the parent's.
 //
-// The model gets four tools. `delegate` takes agent, task and optional model
+// The model gets five 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; the one exception is a `cwd` whose project trust is unresolved,
@@ -34,7 +34,9 @@
 // envelope paths.
 // `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. A delegate can launch children
+// follow-up task, recorded as a new delegation. `delegation_fork` copies a
+// child's context into a new session, leaving the original untouched.
+// A delegate can launch children
 // only below maxDepth and with its current agent allow_nested_delegation grant.
 // Durable identity restores that boundary even on a manual session reopening.
 //
@@ -67,6 +69,7 @@ import {
 } from "./agents.ts";
 import { AGENT_ENV, AUTO_EXIT_ENV, FALLBACK_ENV, registerChild } from "./child.ts";
 import { registerCompletionHost } from "./completion-holds.ts";
+import { type ForkSource, forkTool } from "./fork.ts";
 import { createIdentity, grantsNesting, type Identity, readIdentity, writeIdentity } from "./identity.ts";
 import { activeMark, clearMarks, isFree, readMarks } from "./limits.ts";
 import { createNavigator, OPEN_USAGE, openCompletions, parseOpen } from "./navigator.ts";
@@ -94,7 +97,7 @@ import {
 	reconcileTree,
 	reserveTree,
 } from "./tree-registry.ts";
-import { assertResumeAuthority, historicalRecord, visibleRecords } from "./tree-view.ts";
+import { assertChildAuthority, assertResumeAuthority, historicalRecord, visibleRecords } from "./tree-view.ts";
 import { registerTrustControl } from "./trust-control.ts";
 import { createProactive, createUsageClient, type Proactive, type UsageClient } from "./usage.ts";
 import { registerDelegateWidget } from "./widget.ts";
@@ -135,6 +138,7 @@ const DELEGATION_TOOLS: ReadonlySet<string> = new Set([
 	"delegation_status",
 	"delegation_close",
 	"delegation_resume",
+	"delegation_fork",
 ]);
 /** Asked of every delegate, so the parent gets an answer it can use alone. */
 
@@ -912,7 +916,8 @@ export default function delegate(
 	 * Build the delegate's command line and environment, emit `session:launch`
 	 * and open its window; returns the window id and session. 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.
+	 * `--session-id <id> --name <name>` for a new one (plus `--fork <path>`
+	 * to copy context), `--session <path>` to reopen.
 	 */
 	async function openChild(input: {
 		id: string;
@@ -933,6 +938,7 @@ export default function delegate(
 		onWindowOpened?: () => void;
 		identity: Identity;
 		sessionId?: string;
+		forkSourceCwd?: string;
 	}): Promise<OpenedWindow> {
 		const {
 			id,
@@ -964,7 +970,11 @@ export default function delegate(
 				: workspace.mode === "existing"
 					? `\n\nThe session that started you chose your working directory: ${workspace.cwd}`
 					: "";
-		const prompt = writePromptFile(delegatePrompt(start.agent, managedContext));
+		const forkContext =
+			workspace.mode === "managed" && input.forkSourceCwd
+				? `\n\nThis session was forked from one that worked in ${input.forkSourceCwd}. Work only in ${workspace.cwd}; its uncommitted changes are not here.`
+				: "";
+		const prompt = writePromptFile(delegatePrompt(start.agent, managedContext + forkContext));
 		const argv = [
 			...parentCommand(),
 			...session,
@@ -1060,6 +1070,7 @@ export default function delegate(
 		placement: WindowPlacement;
 		tools: readonly string[];
 		onWindowOpened: () => void;
+		fork?: ForkSource;
 	}): Promise<Launched> {
 		const { id, requestId, workspace, trusted, cwd, sessionDir, start, toolCallId, ctx, placement, onWindowOpened } =
 			input;
@@ -1067,7 +1078,7 @@ export default function delegate(
 		const { id: windowId, session: windowSession } = await openChild({
 			id,
 			name,
-			session: ["--session-id", id, "--name", name],
+			session: [...(input.fork ? ["--fork", input.fork.sessionPath] : []), "--session-id", id, "--name", name],
 			identity: input.identity,
 			workspace,
 			trusted,
@@ -1079,6 +1090,7 @@ export default function delegate(
 			placement,
 			tools: input.tools,
 			onWindowOpened,
+			forkSourceCwd: input.fork?.sourceCwd,
 		});
 		// No task text in the record: the request copy in `sent/` has it.
 		results.recordStart(
@@ -1097,6 +1109,7 @@ export default function delegate(
 				cwd,
 				sessionDir,
 				workspace,
+				...(input.fork ? { forkedFrom: input.fork.id } : {}),
 			},
 			ctx,
 		);
@@ -1109,6 +1122,7 @@ export default function delegate(
 		ctx: ExtensionContext,
 		signal?: AbortSignal,
 		toolCallId?: string,
+		fork?: ForkSource,
 	): Promise<Launched> {
 		admit(start.agent.name, currentRoster(ctx));
 		results.checkStorage(true);
@@ -1119,13 +1133,15 @@ export default function delegate(
 		const parentIdentity = identity.current();
 		const project = parentIdentity
 			? { companion: parentIdentity.rootPlacement, notices: [] }
-			: placementProject(ctx.cwd, companionSuffix);
+			: fork
+				? { companion: fork.rootPlacement, notices: [] }
+				: placementProject(ctx.cwd, companionSuffix);
 		assertRootPlacement(project.companion);
 		const own = identity.child(start.agent, ctx, project.companion);
 		if (parentIdentity) assertParentPlacement(readTree(own.root), own);
 		if (placement === "companion") start.notices.push(...project.notices);
 		const tools = childTools(start.agent);
-		const sessionDir = ctx.sessionManager.getSessionDir();
+		const sessionDir = fork?.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`,
@@ -1188,7 +1204,13 @@ export default function delegate(
 			await reconcileTree(own.root, tmux);
 			admit(start.agent.name, currentRoster(ctx));
 			if (combined?.aborted) throw new Error("the launch was aborted");
-			reservation = reserveTree({ id, sessionId: id, identity: own, sessionDir });
+			reservation = reserveTree({
+				id,
+				sessionId: id,
+				identity: own,
+				sessionDir,
+				...(fork ? { forkedFrom: fork.id } : {}),
+			});
 			if (plan !== undefined) {
 				revalidate(plan);
 				revalidateTrust?.();
@@ -1259,6 +1281,7 @@ export default function delegate(
 				onWindowOpened: () => {
 					windowOpened = true;
 				},
+				fork,
 			});
 		};
 		const runWithRollback = async (): Promise<Launched> => {
@@ -1743,4 +1766,51 @@ export default function delegate(
 	registerDelegate(toolDescription(currentRoster().agents));
 	tracking.registerTools();
 	pi.registerTool(resumer.tool() as never);
+	pi.registerTool(
+		forkTool({
+			results,
+			tmux,
+			delegateSchema: DelegateSchema,
+			roster: rosterFor,
+			parentDefaults,
+			chooseModel: (explicit, agent, models, preferred) =>
+				chooseModel(explicit, agent, models, proactive, agentModels(agent, undefined), preferred),
+			thinkingProblem,
+			authorize: (id, ctx) => {
+				owner.assert();
+				results.checkStorage();
+				const record = results.find(id) ?? viewResults.find(id) ?? historicalRecord(id, ctx);
+				if (record && isStarted(record)) assertChildAuthority(record, ctx, "fork");
+			},
+			admit: (agent, ctx) => admit(agent, currentRoster(ctx)),
+			launch: async (start, source, ctx, signal, toolCallId) => {
+				const launched = await launch(
+					{
+						...start,
+						cwd: start.worktree ? undefined : start.cwd,
+						worktree_source: start.worktree ? start.cwd : undefined,
+					},
+					ctx,
+					signal,
+					toolCallId,
+					source,
+				);
+				return {
+					id: launched.id,
+					agent: start.agent.name,
+					model: start.model,
+					skipped: start.skipped.map(({ model, reason }) => ({ model, reason })),
+					notices: start.notices,
+					thinking: start.thinking,
+					autoExit: start.autoExit,
+					windowId: launched.windowId,
+					windowName: launched.windowName,
+					...(launched.windowSession === undefined ? {} : { windowSession: launched.windowSession }),
+					cwd: launched.cwd,
+					sessionDir: launched.sessionDir,
+					workspace: launched.workspace,
+				};
+			},
+		}) as never,
+	);
 }

package/src/navigator-view.ts

@@ -165,6 +165,7 @@ function detailLines(item: OpenDelegate): string[] {
 		`session file: ${item.live?.sessionFile ?? locateSession({ ...record }, undefined) ?? "not found"}`,
 		`session directory: ${record.sessionDir ?? "not recorded"}`,
 		`result: ${record.result?.status ?? "none received"} · envelope: ${record.result?.envelopePath ?? "none"}`,
+		...(record.forkedFrom === undefined ? [] : [`forked from: ${record.forkedFrom}`]),
 		`resumed from: ${record.resumedFrom ?? "none"} · resumed as: ${item.resumedAs ?? "none"} · auto-exit: ${record.autoExit === true ? "on" : "off"}`,
 		`model: ${record.model} · thinking: ${record.thinking}`,
 	];

package/src/render.ts

@@ -155,6 +155,7 @@ function plainLines(text: string): string[] {
 function idLines(details: MessageDetails): string[] {
 	const lines = [`delegation ${details.id}`, `request ${details.requestId}`];
 	if (details.resumedFrom !== undefined) lines.splice(1, 0, `resumed from ${details.resumedFrom}`);
+	if (details.forkedFrom !== undefined) lines.splice(1, 0, `forked from ${details.forkedFrom}`);
 	if (details.kind === "result") lines.push(`envelope ${tilde(details.envelopePath)}`);
 	else lines.push(`window ${details.windowName}`);
 	lines.push(`cwd ${details.cwd === undefined ? cwdLine(undefined) : tilde(details.cwd)}`);

package/src/result-message.ts

@@ -35,9 +35,14 @@ function limitLine(sessionId: string, status: string): string | undefined {
 }
 
 /** The details that say a delegation reopened an earlier one's session. */
-export function resumeDetails(record: StartedRecorded): { resumedFrom?: string; sessionId?: string } {
+export function resumeDetails(record: StartedRecorded): {
+	resumedFrom?: string;
+	forkedFrom?: string;
+	sessionId?: string;
+} {
 	return {
 		...(record.resumedFrom === undefined ? {} : { resumedFrom: record.resumedFrom }),
+		...(record.forkedFrom === undefined ? {} : { forkedFrom: record.forkedFrom }),
 		...(record.sessionId === undefined ? {} : { sessionId: record.sessionId }),
 	};
 }
@@ -98,7 +103,7 @@ export function resultText(details: ResultDetails): string {
 	const { task } = details;
 	const taskLine = "note" in task ? task.note : `Task: ${task.path}`;
 	return [
-		`[delegate] Result from ${details.agent} (${modelLabel(details.model, details.finishedModel)}), delegation ${details.id}${details.resumedFrom === undefined ? "" : ` (resumed from ${details.resumedFrom})`}, request ${details.requestId}.`,
+		`[delegate] Result from ${details.agent} (${modelLabel(details.model, details.finishedModel)}), delegation ${details.id}${details.resumedFrom === undefined ? "" : ` (resumed from ${details.resumedFrom})`}${details.forkedFrom === undefined ? "" : ` (forked from ${details.forkedFrom})`}, request ${details.requestId}.`,
 		`Status: ${details.status}`,
 		...(details.limit === undefined ? [] : [details.limit]),
 		taskLine,

package/src/result-sessions.ts

@@ -78,6 +78,32 @@ export function finishedModel(sessionPath: string | undefined): string | undefin
 	return undefined;
 }
 
+/** Approximate copied context from the last assistant request, excluding its output. */
+export function sessionInputTokens(sessionPath: string): number | undefined {
+	let lines: string[];
+	try {
+		lines = readFileSync(sessionPath, "utf8").split("\n");
+	} catch {
+		return undefined;
+	}
+	for (let i = lines.length - 1; i >= 0; i--) {
+		let entry: { type?: unknown; message?: { role?: unknown; usage?: Record<string, unknown> } };
+		try {
+			entry = JSON.parse(lines[i]);
+		} catch {
+			continue;
+		}
+		if (entry?.type !== "message" || entry.message?.role !== "assistant") continue;
+		const usage = entry.message.usage;
+		const counts = [usage?.input, usage?.cacheRead, usage?.cacheWrite];
+		if (!counts.every((count): count is number => typeof count === "number" && Number.isFinite(count) && count >= 0))
+			return undefined;
+		const total = counts.reduce((sum, count) => sum + count, 0);
+		return Number.isFinite(total) && total > 0 ? total : undefined;
+	}
+	return undefined;
+}
+
 /** One session-file line, as much of it as the branch walk reads. */
 type BranchEntry = { type?: unknown; id?: unknown; parentId?: unknown; thinkingLevel?: unknown };
 

package/src/results.ts

@@ -66,6 +66,8 @@ export type Delegation = {
 	workspace?: Workspace;
 	/** The delegation this one resumed, when it reopened that delegation's session. */
 	resumedFrom?: string;
+	/** The delegation whose context this new session copied. */
+	forkedFrom?: string;
 	/** The Pi session id; absent means `id`. A resumed delegation holds the session id of the one it resumed. */
 	sessionId?: string;
 };
@@ -113,6 +115,7 @@ type CommonDetails = {
 	id: string;
 	/** The delegation this one resumed. */
 	resumedFrom?: string;
+	forkedFrom?: string;
 	/** The Pi session id when it is not `id`: a resumed delegation's. */
 	sessionId?: string;
 	requestId: string;
@@ -375,7 +378,7 @@ export function createResults(
 			windowName: record.windowName,
 		};
 		const content = [
-			`[delegate] Delegation ${record.id}${record.resumedFrom === undefined ? "" : ` (resumed from ${record.resumedFrom})`} (${record.agent}, ${modelLabel(record.model, finished)}), request ${record.requestId}, closed without a result: its window ${record.windowName} is gone and no reply arrived.`,
+			`[delegate] Delegation ${record.id}${record.resumedFrom === undefined ? "" : ` (resumed from ${record.resumedFrom})`}${record.forkedFrom === undefined ? "" : ` (forked from ${record.forkedFrom})`} (${record.agent}, ${modelLabel(record.model, finished)}), request ${record.requestId}, closed without a result: its window ${record.windowName} is gone and no reply arrived.`,
 			`Working directory: ${cwdLine(record.cwd)}`,
 			...(record.workspace === undefined ? [] : [`Workspace: ${workspaceLine(record.workspace)}`]),
 			`Delegate session: ${session ?? sessionIdOf(record)}`,

package/src/resume-checks.ts

@@ -53,28 +53,32 @@ export function isDirectory(path: string): boolean {
 export type SessionFile = { path: string; cwd: string; dir: string };
 
 /** Step 5: the session file, and the directory its header says Pi will run it in. */
-export function sessionFor(record: StartedRecorded, ctx: ExtensionContext): SessionFile {
+export function sessionFor(
+	record: StartedRecorded,
+	ctx: ExtensionContext,
+	purpose: "resumable" | "forkable" = "resumable",
+): SessionFile {
 	const dir = record.sessionDir ?? ctx.sessionManager.getSessionDir();
 	const path = locateSession(record, ctx.sessionManager.getSessionDir());
 	if (path === undefined) {
 		throw new Error(
-			`no session file for session ${sessionIdOf(record)} was found in ${dir}, so delegation ${record.id} is not resumable`,
+			`no session file for session ${sessionIdOf(record)} was found in ${dir}, so delegation ${record.id} is not ${purpose}`,
 		);
 	}
 	if (!isAbsolute(path) || !isAbsolute(dir)) {
 		throw new Error(
-			`the session file ${path} or its directory ${dir} is not an absolute path, so delegation ${record.id} is not resumable`,
+			`the session file ${path} or its directory ${dir} is not an absolute path, so delegation ${record.id} is not ${purpose}`,
 		);
 	}
 	const cwd = sessionHeaderCwd(path);
 	if (cwd === undefined) {
 		throw new Error(
-			`could not read a working directory from the header of ${path}, so delegation ${record.id} is not resumable`,
+			`could not read a working directory from the header of ${path}, so delegation ${record.id} is not ${purpose}`,
 		);
 	}
 	if (!isDirectory(cwd)) {
 		throw new Error(
-			`delegation ${record.id}'s session runs in ${cwd}, which no longer exists, so it is not resumable (a removed worktree cannot be resumed)`,
+			`delegation ${record.id}'s session runs in ${cwd}, which no longer exists, so it is not ${purpose} (a removed worktree cannot be ${purpose === "resumable" ? "resumed" : "forked"})`,
 		);
 	}
 	return { path, cwd, dir };
@@ -144,7 +148,7 @@ export function recordCheck(
 
 /** The thinking level and model a resume runs with; throws when the level is invalid or no model can be used. */
 export async function settleModel(
-	deps: ResumeDeps,
+	deps: Pick<ResumeDeps, "parentDefaults" | "thinkingProblem" | "chooseModel">,
 	input: {
 		record: StartedRecorded;
 		agent: Agent;

package/src/tracking.ts

@@ -81,6 +81,7 @@ const StartedSchema = Type.Object({
 	thinking: Type.String(),
 	autoExit: Type.Boolean(),
 	resumedFrom: Type.Optional(Type.String()),
+	forkedFrom: Type.Optional(Type.String()),
 	windowId: Type.String(),
 	windowName: Type.String(),
 	windowSession: Type.Optional(Type.String()),
@@ -182,6 +183,7 @@ function viewText({ record, state, name, sessionPath, lastActive, snapshot, resu
 		`  identity: session ${sessionIdOf(record)} · parent ${record.identity?.parent ?? "this session"} · root ${record.identity?.root ?? "this session"} · depth ${record.identity?.depth ?? 1}`,
 		...(accountingFor(record) ? [`  shared accounting: ${accountingFor(record)} (not result processing)`] : []),
 		...(record.resumedFrom === undefined ? [] : [`  resumed from ${record.resumedFrom}`]),
+		...(record.forkedFrom === undefined ? [] : [`  forked from ${record.forkedFrom}`]),
 		...(resumedAs === undefined ? [] : [`  resumed as ${resumedAs}`]),
 		`  state: ${stateLine(state, record)}${seen}`,
 		`  window: ${record.windowName} (${record.windowId})${windowSession === undefined || windowSession === "" ? "" : ` in session ${windowSession}`}`,
@@ -223,6 +225,7 @@ function viewDetails({
 		thinking: record.thinking,
 		autoExit: record.autoExit === true,
 		...(record.resumedFrom === undefined ? {} : { resumedFrom: record.resumedFrom }),
+		...(record.forkedFrom === undefined ? {} : { forkedFrom: record.forkedFrom }),
 		windowId: record.windowId,
 		windowName: record.windowName,
 		...(windowSession === undefined || windowSession === "" ? {} : { windowSession }),

package/src/tree-registry.ts

@@ -82,7 +82,7 @@ function validateFields(entry: TreeEntry): void {
 	for (const key of ["finished", "gone", "closed", "closing", "createPending"] as const)
 		if (entry[key] !== undefined && typeof entry[key] !== "boolean")
 			throw new Error(`invalid ${key} in tree entry ${entry.id}`);
-	for (const key of ["requestId", "windowId", "windowName", "cwd", "sessionDir", "resumedFrom"] as const)
+	for (const key of ["requestId", "windowId", "windowName", "cwd", "sessionDir", "resumedFrom", "forkedFrom"] as const)
 		if (entry[key] !== undefined && typeof entry[key] !== "string")
 			throw new Error(`invalid ${key} in tree entry ${entry.id}`);
 }
@@ -264,6 +264,7 @@ export function publishTreeRecords(root: string, parent: string, records: Record
 					ownerPid: process.pid,
 					phase: "started",
 					resumedFrom: record.resumedFrom,
+					forkedFrom: record.forkedFrom,
 				};
 				state.entries.push(entry);
 			}

package/src/tree-types.ts

@@ -16,6 +16,7 @@ export type TreeEntry = {
 	sessionDir?: string;
 	workspace?: Workspace;
 	resumedFrom?: string;
+	forkedFrom?: string;
 	launch?: Delegation;
 	finished?: boolean;
 	gone?: boolean;
@@ -28,5 +29,5 @@ export type TreeEntry = {
 export type TreeClose = { id: string; target: string; entries: string[] };
 export type TreeState = { version: 1; root: string; entries: TreeEntry[]; closes?: TreeClose[] };
 export type Reservation = { root: string; id: string };
-export type TreeIntent = Pick<TreeEntry, "id" | "sessionId" | "identity" | "resumedFrom" | "sessionDir">;
+export type TreeIntent = Pick<TreeEntry, "id" | "sessionId" | "identity" | "resumedFrom" | "forkedFrom" | "sessionDir">;
 export type TreeCounts = { concurrent: number; lifetime: number };

package/src/tree-view.ts

@@ -33,24 +33,35 @@ export function belongsTo(record: Recorded, ctx: ExtensionContext): boolean {
 	// never by a branch copied into a fresh session file.
 	return !ctx.sessionManager.getHeader?.()?.parentSession;
 }
-export function assertResumeAuthority(record: StartedRecorded, ctx: ExtensionContext): void {
+export function assertChildAuthority(
+	record: StartedRecorded,
+	ctx: ExtensionContext,
+	operation: "resume" | "fork",
+): void {
 	const child: Identity | undefined = recordedIdentity(record);
 	if (!belongsTo(record, ctx))
 		throw new Error(
-			`only direct parent ${child?.parent ?? "(original session)"} may resume delegation ${record.id}; reopen that parent session`,
+			`only direct parent ${child?.parent ?? "(original session)"} may ${operation} delegation ${record.id}; reopen that parent session`,
 		);
-	if (!child) throw new Error(`delegation ${record.id} has no original root placement identity; resume refused`);
+	if (!child) throw new Error(`delegation ${record.id} has no original root placement identity; ${operation} refused`);
 	const parent: Identity | undefined = readIdentity(ctx.sessionManager.getSessionId());
 	if (
 		child.root !== (parent?.root ?? ctx.sessionManager.getSessionId()) ||
 		child.depth !== (parent?.depth ?? 0) + 1 ||
 		(parent && child.rootPlacement !== parent.rootPlacement)
 	)
-		throw new Error(`delegation ${record.id} has inconsistent root/depth or rootPlacement ownership; resume refused`);
+		throw new Error(
+			`delegation ${record.id} has inconsistent root/depth or rootPlacement ownership; ${operation} refused`,
+		);
 	if (child.depth > maxDepth())
 		throw new Error(
 			`delegation ${record.id} depth ${child.depth} exceeds maxDepth ${maxDepth()} in squire/settings.json`,
 		);
+}
+export function assertResumeAuthority(record: StartedRecorded, ctx: ExtensionContext): void {
+	assertChildAuthority(record, ctx, "resume");
+	const child = recordedIdentity(record);
+	if (!child) throw new Error(`delegation ${record.id} has no original root placement identity; resume refused`);
 	const state = readTree(child.root);
 	const newer: TreeEntry | undefined = newestSuccessor(state.entries, record.id);
 	if (newer)
@@ -197,6 +208,7 @@ function registryView(entry: TreeEntry): StartedRecorded {
 		sessionDir: entry.sessionDir,
 		workspace: entry.workspace,
 		resumedFrom: entry.resumedFrom,
+		forkedFrom: entry.forkedFrom,
 	};
 }
 function hierarchy(records: Recorded[], viewer: string): Recorded[] {