pi-squire 0.18.0 → 0.18.2

package/CHANGELOG.md

@@ -6,6 +6,47 @@ follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.18.2] - 2026-11-01
+
+### Fixed
+
+- Agents without a `tools:` field inherit available deferred and codemode tools
+  from root sessions, just as they already did from nested delegates. Inactive
+  direct tools and hidden tools remain excluded. Pi initially declares the
+  selected tools in the child; extensions that enable optional tools on demand
+  must deselect them during child startup. This can increase initial declarations
+  for root-launched delegates whose extensions do not deselect those tools.
+- Creating a companion session no longer saves the first delegate's environment,
+  including `PI_UNATTENDED` and API keys, into the session for later windows to
+  inherit. Each delegate still receives its own launch environment. Existing
+  polluted sessions are not changed. The fresh-companion argument test now pins
+  window-local environment delivery instead of session-level `-e` options.
+  Launches still pass only Squire's environment and `session:launch` additions,
+  never a copy of the parent's full process environment.
+- tmux failures report a bounded subcommand error instead of raw process errors
+  or stderr that could expose launch arguments or environment values. The two
+  failed ownership-recheck tests now expect the bounded error wording.
+- The discovery-count regression uses a controlled clock so additional parallel
+  test load does not turn its structural count assertion into a timing failure.
+  The separate real-time discovery deadline test and 200 ms product bound are
+  unchanged.
+
+## [0.18.1] - 2026-11-01
+
+### Changed
+
+- The delegation tools put about 70% less text in a model's context: in a
+  codemode root their declarations drop from about 5,100 estimated tokens to
+  about 1,400. The descriptions and parameter notes are shorter, and the output
+  schemas carry no field descriptions. `workspace`, `workspaceSnapshot`, and a
+  workspace attempt's `plan` and `attempt` are declared by their discriminant
+  and directory only, with their other fields left open; the structured data
+  itself is unchanged. Tests that pinned the old wording are updated.
+- A delegate's appended prompt is its agent body and working-directory line
+  only. The paragraph naming the parent's address and the final-message rule
+  are in the per-run `squire_delegate_task` section alone, where they were
+  already repeated.
+
 ## [0.18.0] - 2026-11-01
 
 ### Changed
@@ -1008,7 +1049,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.18.0...HEAD
+[Unreleased]: https://github.com/gvanderclay/pi-squire/compare/v0.18.2...HEAD
+[0.18.2]: https://github.com/gvanderclay/pi-squire/compare/v0.18.1...v0.18.2
+[0.18.1]: https://github.com/gvanderclay/pi-squire/compare/v0.18.0...v0.18.1
 [0.18.0]: https://github.com/gvanderclay/pi-squire/compare/v0.17.0...v0.18.0
 [0.17.0]: https://github.com/gvanderclay/pi-squire/compare/v0.16.0...v0.17.0
 [0.16.0]: https://github.com/gvanderclay/pi-squire/compare/v0.15.0...v0.16.0

package/README.md

@@ -992,11 +992,14 @@ are not checked against the parent's tools, at top level or nested: normal Pi
 extension discovery or `session:launch` customization can provide tools in the
 child.
 
-- No `tools` field: the delegate gets the parent session's tools as they are
-  when the launch (or resume) starts: active tools for a top-level launch, or
-  available tools including codemode/deferred operations for a nested one, passed as
-  `--tools`, plus the `delegateTools` entries. A parent limited to `read`
-  gives such a delegate only `read`.
+- No `tools` field: the delegate gets the parent session's available tools
+  when the launch (or resume) starts, at any depth: active tools plus registered
+  codemode/deferred operations, excluding hidden tools and inactive direct tools,
+  passed as `--tools`, plus the `delegateTools` entries. Pi initially declares
+  these selected tools in the child, even when their exposure is codemode or
+  deferred. An extension can deselect optional tools during child startup and
+  enable them later. A parent with only `read` available gives such a delegate
+  only `read`.
 - An empty `tools` field, `tools:` or `tools: []`: the delegate gets no tools
   except the `delegateTools` entries. With none of those either, it starts
   with `--no-tools`.
@@ -1063,14 +1066,14 @@ limit, it resolves each entry the way Pi resolves `--model`: an exact
 order the entries are listed. No entry may be a `*` pattern: a `model` or
 `fallback` entry with `*` makes the file invalid, and the agent is disabled.
 
-The body is followed by one fixed final-message line and a paragraph naming the
-parent session's address. The delegate's task arrives as a message from that
+Each run of the delegate also gets a system-prompt section naming the parent
+session's address. The delegate's task arrives as a message from that
 session, and that message and every later one from the same address are
 instructions to follow as given. Other sessions are colleagues: the delegate
 may answer them, but checks with the parent before doing work the parent did
-not ask for. The paragraph names no provider, package or tool, so it holds
-whatever `message:*` provider delivers the task. `prompt_mode: replace` builds
-the prompt exactly as every delegate was built before `prompt_mode` existed.
+not ask for. Its final message reaches the parent on its own. The section names
+no provider, package or tool, so it holds whatever `message:*` provider
+delivers the task. `prompt_mode: replace` appends the body as written.
 
 An agent file that cannot be used is invalid, and its agent is disabled:
 frontmatter that is not readable YAML or not a set of fields, an `enabled` or
@@ -1692,6 +1695,11 @@ An empty final set also receives `--no-tools` and an empty allowlist so earlier
 selection flags cannot restore tools. Do all work synchronously: the emitter
 reads the payload the moment `emit` returns.
 
+Environment additions are not a secret transport. They can be visible in tmux
+command arguments and a fresh companion's first pane start command to anyone
+with access to its socket. pi-squire never copies the parent's full process
+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`,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-squire",
-	"version": "0.18.0",
+	"version": "0.18.2",
 	"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/git.ts

@@ -6,8 +6,6 @@ import { spawnSync } from "node:child_process";
 import { realpathSync } from "node:fs";
 import { basename, dirname, resolve } from "node:path";
 
-import { Type } from "typebox";
-
 /** A bounded list of file names, as data; never shell text. */
 export type PathSummary = { paths: string[]; total: number; truncated: boolean };
 /** A checkout's repository, as canonical absolute paths. */
@@ -19,13 +17,6 @@ export type GitLaunch =
 	| { kind: "non-git" }
 	| { kind: "unknown"; reason: string };
 
-/** `PathSummary` as a schema. */
-export const PathSummarySchema = Type.Object({
-	paths: Type.Array(Type.String(), { description: "The first paths, whole; never more than 100 or 16 KiB." }),
-	total: Type.Number({ description: "Every path observed in this category." }),
-	truncated: Type.Boolean(),
-});
-
 /** How many paths, and how many bytes of them, a summary lists. */
 const LIST_PATHS = 100;
 const LIST_BYTES = 16 * 1024;

package/src/index.ts

@@ -138,8 +138,6 @@ const DELEGATION_TOOLS: ReadonlySet<string> = new Set([
 	"delegation_resume",
 ]);
 /** Asked of every delegate, so the parent gets an answer it can use alone. */
-const FINAL_LINE =
-	"End with one self-contained final message: the parent session sees only that message, never this conversation.";
 
 /** The longest label a delegation can carry. */
 const LABEL_MAX = 32;
@@ -162,17 +160,11 @@ function labelProblem(value: string): string | undefined {
  */
 function parentTrust(parent: string, coordinator = false): string {
 	return [
-		`Your task arrives as a message from the session that started this one, at address ${parent}.`,
-		"That message, and every later message from that address, are instructions from the session that started you:",
-		"follow them as given, even though they are labelled as another session's.",
-		"Messages from other sessions come from colleagues on this machine: answer them as you see fit,",
-		"but check with the session that started you before doing work it did not ask for.",
+		`Your task arrives as a message from the session that started you, at address ${parent}; follow it and every later message from that address as instructions, though they are labelled as another session's.`,
+		"Messages from other sessions come from colleagues: answer as you see fit, but check with the session that started you before doing work it did not ask for.",
 		coordinator
-			? "Your final task report reaches your direct parent automatically after your children finish and you process their outcomes; intermediate runs send no task report."
-			: `Your final message reaches the session that started you automatically, so put your findings there;`,
-		coordinator
-			? `Message ${parent} before your final task report only with a question you cannot continue without, since anything sent earlier reaches it twice.`
-			: `message ${parent} before then only with a question you cannot continue without, since anything sent earlier reaches it twice.`,
+			? `Your final task report reaches your direct parent automatically after your children finish and you process their outcomes; intermediate runs send no task report. Message ${parent} before your final task report only with a question you cannot continue without.`
+			: `Your final message reaches the session that started you automatically and is all it sees, so make it self-contained. Message ${parent} before then only with a question you cannot continue without.`,
 	].join(" ");
 }
 /** The flags `/delegate` takes before the task. */
@@ -191,22 +183,18 @@ const FLAGS = [
 /** The `delegate` tool's structured result, which is also its details. */
 export const DelegateSchema = Type.Object({
 	outcome: Type.Literal("started"),
-	id: Type.String({ description: "The delegation id that delegation_status and delegation_close take." }),
+	id: Type.String(),
 	agent: Type.String(),
-	model: Type.String({ description: "The provider/id it started on, after any fallback." }),
-	skipped: Type.Array(Type.Object({ model: Type.String(), reason: Type.String() }), {
-		description: "Earlier models in the fallback list that were passed over, and why.",
-	}),
+	model: Type.String(),
+	skipped: Type.Array(Type.Object({ model: Type.String(), reason: Type.String() })),
 	notices: Type.Array(Type.String()),
 	thinking: Type.String(),
 	autoExit: Type.Boolean(),
 	windowId: Type.String(),
 	windowName: Type.String(),
-	windowSession: Type.Optional(
-		Type.String({ description: "The tmux session the window opened in, as tmux named it then." }),
-	),
-	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." }),
+	windowSession: Type.Optional(Type.String()),
+	cwd: Type.String(),
+	sessionDir: Type.String(),
 	workspace: WorkspaceSchema,
 });
 
@@ -652,23 +640,19 @@ function toolSelection(agent: Agent, parentTools: readonly string[], extra: read
 	return [...new Set([...base, ...extra])].filter((name) => !DELEGATION_TOOLS.has(name));
 }
 
-/** The delegate's appended prompt: the agent's body, then the lines every delegate gets. */
-function delegatePrompt(agent: Agent, parent: string, managedContext: string, coordinator: boolean): string {
-	const final = coordinator
-		? "End the task with one self-contained final report to your direct parent after your child tasks finish and you process their outcomes."
-		: FINAL_LINE;
-	const tail = `${final}\n\n${parentTrust(parent, coordinator)}${managedContext}`;
-	if (agent.prompt === "") return tail;
+/** The delegate's appended prompt: the agent's body and where it works; the run-time section carries the parent's address. */
+function delegatePrompt(agent: Agent, managedContext: string): string {
+	if (agent.prompt === "") return managedContext.trimStart();
 	// `replace` is how every delegate was built before `prompt_mode`, byte for byte.
 	const body =
 		agent.promptMode === "replace" ? agent.prompt : `<agent_instructions>\n${agent.prompt}\n</agent_instructions>`;
-	return `${body}\n\n${tail}`;
+	return `${body}${managedContext}`;
 }
 
 /** 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, 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.";
+		"Start a delegate Pi session on a self-contained task in a background tmux window. Its result arrives later as a message that starts your next turn, so keep working or end your turn; do not poll delegation_status or mail it just to wait.";
 	if (agents.length === 0) {
 		return `${intro}\n\nNo agents are defined yet. Add ${whereAgentsGo()}.`;
 	}
@@ -678,11 +662,7 @@ function toolDescription(agents: readonly Agent[]): string {
 		"Agents:",
 		...agents.map(rosterLine),
 		"",
-		"`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, except a field the agent locks; 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.",
+		"The delegate sees only the task and its agent prompt. State the question, the decision it feeds, what is known or ruled out, and where to start. For a long report, name a file to write and ask for the conclusion back.",
 	].join("\n");
 }
 
@@ -827,13 +807,13 @@ export default function delegate(
 	/**
 	 * The delegate's tools for a launch or resume starting now: the agent's
 	 * named tools, or the parent's current tools (including indirect callable
-	 * tools when nested, less any `-name` entries), then `delegateTools`.
+	 * tools, less any `-name` entries), then `delegateTools`.
 	 * Throws, naming the file, on an invalid setting.
 	 */
 	function childTools(agent: Agent): string[] {
 		const selected = toolSelection(
 			agent,
-			agent.tools === undefined ? (identity.current() ? availableTools(pi) : pi.getActiveTools()) : [],
+			agent.tools === undefined ? availableTools(pi) : [],
 			delegateTools(getAgentDir()),
 		);
 		if (grantsNesting(agent, (identity.current()?.depth ?? 0) + 1)) selected.push(...DELEGATION_TOOLS);
@@ -994,9 +974,7 @@ 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, parent, managedContext, grantsNesting(start.agent, own.depth)),
-		);
+		const prompt = writePromptFile(delegatePrompt(start.agent, managedContext));
 		const argv = [
 			...parentCommand(),
 			...session,
@@ -1526,53 +1504,32 @@ export default function delegate(
 		label: "Delegate",
 		description,
 		parameters: Type.Object({
-			agent: Type.String({ description: "Roster agent name to run." }),
-			task: Type.String({
-				description: "The task for the delegate. It sees this and its agent prompt, nothing else of this session.",
-			}),
-			model: Type.Optional(
-				Type.String({
-					description:
-						"provider/id model for this call; defaults to the agent's, or this session's when it names none. Not used when the agent locks model.",
-				}),
-			),
-			thinking: Type.Optional(
-				Type.String({
-					description: `Thinking level (${THINKING_LEVELS.join(", ")}); defaults to the agent's, or this session's when it names none. Not used when the agent locks thinking.`,
-				}),
-			),
+			agent: Type.String({ description: "Roster agent name." }),
+			task: Type.String(),
+			model: Type.Optional(Type.String({ description: "provider/id; defaults to the agent's." })),
+			thinking: Type.Optional(Type.String({ description: `${THINKING_LEVELS.join(", ")}; defaults to the agent's.` })),
 			label: Type.Optional(
 				Type.String({
-					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>.`,
+					description: `Window and session name suffix: letters, digits, _ or -, at most ${LABEL_MAX}.`,
 				}),
 			),
 			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.",
-				}),
+				Type.Union([Type.String(), Type.Null()], { description: "Existing directory to run in. Not 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.",
+					description: "New branch name: creates a managed worktree from HEAD or worktree_base. Not 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.",
-				}),
+				Type.Union([Type.String(), Type.Null()], { description: "Git checkout to create the worktree from." }),
 			),
 			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.",
-				}),
+				Type.Union([Type.String(), Type.Null()], { description: "Local commit-ish for the worktree branch." }),
 			),
 			auto_exit: Type.Optional(
 				Type.Boolean({
-					description:
-						"Close the delegate's window once it finishes; defaults to the agent's setting. False keeps it open to talk to it by mail after its result.",
+					description: "Close the window when it finishes; defaults to the agent's. False keeps it open for mail.",
 				}),
 			),
 		}),

package/src/render.ts

@@ -281,7 +281,7 @@ export function renderDelegateResult(
 		const text = result.content.map((part) => part.text ?? "").join("\n");
 		return new Text(context.isError ? theme.fg("error", text) : text, 0, 0);
 	}
-	const started = details as Static<typeof DelegateSchema>;
+	const started = details as Static<typeof DelegateSchema> & { workspace: Workspace };
 	const lines = [
 		`${theme.fg("accent", "●")} ${theme.fg("toolTitle", theme.bold(started.windowName))}${theme.fg(
 			"dim",

package/src/resume.ts

@@ -171,7 +171,7 @@ async function ensureExited(record: StartedRecorded, tmux: TmuxClient): Promise<
 function resultSchema(delegateSchema: TObject): TObject {
 	return Type.Object({
 		...delegateSchema.properties,
-		resumedFrom: Type.String({ description: "The delegation whose session this one reopened." }),
+		resumedFrom: Type.String(),
 	});
 }
 
@@ -391,26 +391,15 @@ function resumeTool(deps: ResumeDeps): ToolDef {
 		name: "delegation_resume",
 		label: "Resume delegation",
 		description:
-			"Only this session’s direct children may be resumed; viewing a descendant does not grant authority, and fork/clone copies must return to the original parent. Current depth, grants, caps, tools and trust are checked again. Continue an exited delegate with a follow-up task: reopen its own session, so it keeps the context it built, in a new window. The follow-up is recorded as a new delegation, and its result arrives as a message on its own, like a delegate's. Use it when the next task needs what the delegate already read or decided; for unrelated work, use delegate. It refuses a delegation that is still running (send it a message instead), one whose window is still open, an older delegation of a chain that was already resumed (it names the newest), and one whose working directory is gone, a removed worktree included. A delegate whose window was killed mid-turn can be resumed.",
+			"Continue an exited direct child in its own session, so it keeps the context it built, with a follow-up task in a new window. It is recorded as a new delegation whose result arrives as a message. For unrelated work, use delegate. Refuses a running delegation (mail it instead), an open window, an older link of a resumed chain (it names the newest) and a missing working directory.",
 		parameters: Type.Object({
-			id: Type.String({ description: "The delegation to resume, from a delegate result or delegation_status." }),
-			task: Type.String({
-				description: "The follow-up task. The delegate sees its earlier conversation plus this.",
-			}),
-			model: Type.Optional(
-				Type.String({
-					description:
-						"provider/id to resume on; used as given. Omit to continue on the model the delegate finished on, or its agent's next fallback when that one is unavailable. Not used when the agent locks model: the agent's current model applies.",
-				}),
-			),
+			id: Type.String({ description: "The newest delegation id of the child." }),
+			task: Type.String(),
+			model: Type.Optional(Type.String({ description: "provider/id; defaults to the model it finished on." })),
 			thinking: Type.Optional(
-				Type.String({
-					description: `Thinking level (${THINKING_LEVELS.join(", ")}); defaults to the level the delegate last ran on, from its session. Not used when the agent locks thinking: the agent's current level applies.`,
-				}),
-			),
-			auto_exit: Type.Optional(
-				Type.Boolean({ description: "Close the window once it finishes; defaults to the delegation's setting." }),
+				Type.String({ description: `${THINKING_LEVELS.join(", ")}; defaults to the level it last ran on.` }),
 			),
+			auto_exit: Type.Optional(Type.Boolean({ description: "Defaults to the delegation's setting." })),
 		}),
 		outputSchema: resultSchema(deps.delegateSchema),
 		// Opens a window and removes nothing but an exited window of the old run; each call starts another run.

package/src/snapshot.ts

@@ -16,11 +16,9 @@ import {
 	type GitPosition,
 	onePath,
 	type PathSummary,
-	PathSummarySchema,
 	pendingPaths,
 	summarize,
 } from "./git.ts";
-import { PositionSchema } from "./workspace.ts";
 
 /**
  * A checkout as observed at one moment: its position and head against the
@@ -41,31 +39,10 @@ export type WorkspaceSnapshot =
 			pending: { staged: PathSummary; unstaged: PathSummary; untracked: PathSummary; conflicted: PathSummary };
 	  };
 
-/** `WorkspaceSnapshot` as a schema, for `delegation_status`. */
-export const WorkspaceSnapshotSchema = Type.Union(
-	[
-		Type.Object({ kind: Type.Literal("non-git") }),
-		Type.Object({ kind: Type.Literal("unknown"), reason: Type.String() }),
-		Type.Object({
-			kind: Type.Literal("git"),
-			position: PositionSchema,
-			head: Type.String(),
-			baseline: Type.String({ description: "The launch commit the changes are counted from." }),
-			ahead: Type.Number({ description: "Commits reachable from head but not from the baseline." }),
-			workingState: Type.Union([Type.Literal("clean"), Type.Literal("dirty")]),
-			committed: PathSummarySchema,
-			pending: Type.Object({
-				staged: PathSummarySchema,
-				unstaged: PathSummarySchema,
-				untracked: PathSummarySchema,
-				conflicted: PathSummarySchema,
-			}),
-		}),
-	],
-	{
-		description:
-			"The checkout observed now: git (changes since the launch commit, committed and pending), non-git, or unknown with a reason.",
-	},
+/** `WorkspaceSnapshot` as a schema for `delegation_status`: the discriminant, the rest open. */
+export const WorkspaceSnapshotSchema = Type.Object(
+	{ kind: Type.Union([Type.Literal("git"), Type.Literal("non-git"), Type.Literal("unknown")]) },
+	{ additionalProperties: true },
 );
 
 /** Reporting limits for one snapshot; never evidence for deleting anything. */

package/src/tmux.ts

@@ -18,7 +18,6 @@ export type TmuxWindow = { id: string; session: string; name: string; exited: bo
 /** A window just opened: its id and the name of the session it is in, when known. */
 export type OpenedWindow = { id: string; session: string | undefined };
 
-/** The oldest tmux delegate windows need: `new-session -e` arrived in 3.2. */
 export const MIN_TMUX = { major: 3, minor: 2 } as const;
 
 export type TmuxVersion = { text: string; major: number; minor: number };
@@ -124,8 +123,8 @@ function runTmux(args: string[], timeout: number): Promise<string> {
 					reject(new Error(`tmux ${args[0]} timed out after ${timeout / 1000} s`));
 					return;
 				}
-				const detail = typeof stderr === "string" && stderr.trim() !== "" ? stderr.trim() : error.message;
-				reject(new Error(detail));
+				const reason = ["duplicate session", "can't find session"].find((text) => stderr.includes(text));
+				reject(new Error(`tmux ${args[0]} failed${reason === undefined ? "" : `: ${reason}`}`));
 				return;
 			}
 			resolve(stdout);
@@ -215,8 +214,17 @@ async function openCompanion(run: Run, spec: WindowSpec, base: string): Promise<
 				continue;
 			}
 		}
-		const args = ["new-session", "-d", "-s", session, "-n", spec.name, "-c", spec.cwd, ...envArgs(spec)];
-		args.push("-P", "-F", "#{window_id}", "--", ...spec.argv);
+		const args = ["new-session", "-d", "-s", session, "-n", spec.name, "-c", spec.cwd];
+		// new-session -e persists in the session; env confines these values to its first window.
+		args.push(
+			"-P",
+			"-F",
+			"#{window_id}",
+			"--",
+			"env",
+			...Object.entries(spec.env).map(([key, value]) => `${key}=${value}`),
+			...spec.argv,
+		);
 		args.push(";", "set-option", "-t", `=${session}:`, COMPANION_OPTION, "1");
 		args.push(";", "set-option", "-t", `=${session}:`, "detach-on-destroy", "off");
 		certainty = "unknown";

package/src/tool-names.ts

@@ -12,7 +12,7 @@ export function toolMatches(pattern: string, name: string): boolean {
 
 /**
  * The operations this session can reach: active tools plus codemode and
- * deferred ones, never hidden ones. A nested delegate with no `tools` field
+ * deferred ones, never hidden ones. A delegate with no `tools` field
  * inherits these. Includes active model-only operations, though
  * ctx.executeTool cannot call those.
  */

package/src/tracking-attempt.ts

@@ -1,46 +1,7 @@
 import { Type } from "typebox";
-import { WorktreePlanSchema } from "./workspace.ts";
 
 const ATTEMPT_PHASES = ["planned", "created", "rolled-back", "retained", "interrupted"] as const;
-
-const ResourceSchema = Type.Union(
-	[
-		Type.Object({ kind: Type.Literal("none") }),
-		Type.Object({ kind: Type.Literal("branch"), branch: Type.String(), head: Type.String() }),
-		Type.Object({ kind: Type.Literal("worktree"), cwd: Type.String(), branch: Type.String(), head: Type.String() }),
-		Type.Object({
-			kind: Type.Literal("unknown"),
-			reason: Type.String(),
-			observedPaths: Type.Array(Type.String()),
-			observedRefs: Type.Array(Type.String()),
-		}),
-	],
-	{ description: "What is known to exist for a launch that has no window, as facts." },
-);
-
-const AttemptStateSchema = Type.Union([
-	Type.Object({ phase: Type.Literal("planned"), resources: ResourceSchema }),
-	Type.Object({ phase: Type.Literal("created"), resources: ResourceSchema }),
-	Type.Object({
-		phase: Type.Literal("rolled-back"),
-		resources: Type.Object({ kind: Type.Literal("none") }),
-		cause: Type.String(),
-	}),
-	Type.Object({
-		phase: Type.Literal("retained"),
-		resources: ResourceSchema,
-		cause: Type.String(),
-		recovery: Type.Array(Type.String(), {
-			description: "Non-forced commands that remove exactly the resources known to remain.",
-		}),
-	}),
-	Type.Object({
-		phase: Type.Literal("interrupted"),
-		resources: ResourceSchema,
-		lastPhase: Type.Union([Type.Literal("planned"), Type.Literal("created")]),
-		reason: Type.String(),
-	}),
-]);
+const PHASE = Type.Union(ATTEMPT_PHASES.map((phase) => Type.Literal(phase)));
 
 /** A managed launch that has no window: never running, never closable, with no window id. */
 export const AttemptSchema = Type.Object({
@@ -52,14 +13,8 @@ export const AttemptSchema = Type.Object({
 	thinking: Type.String(),
 	name: Type.Optional(Type.String()),
 	sessionDir: Type.String(),
-	plan: WorktreePlanSchema,
-	attempt: AttemptStateSchema,
-	requestId: Type.Optional(Type.String({ description: "The task's request id, only when mail really returned one." })),
-	state: Type.Union(
-		ATTEMPT_PHASES.map((phase) => Type.Literal(phase)),
-		{
-			description:
-				"planned, created: a launch in progress. rolled-back: failed before a window and everything was removed. retained: failed before a window and something remains (see attempt.recovery). interrupted: the parent ended mid-launch; what exists is unknown. No window was opened.",
-		},
-	),
+	plan: Type.Object({ branch: Type.String(), destination: Type.String() }, { additionalProperties: true }),
+	attempt: Type.Object({ phase: PHASE }, { additionalProperties: true }),
+	requestId: Type.Optional(Type.String()),
+	state: PHASE,
 });

package/src/tracking.ts

@@ -71,46 +71,30 @@ const StartedSchema = Type.Object({
 	root: Type.Optional(Type.String()),
 	depth: Type.Optional(Type.Number()),
 	accounting: Type.Optional(Type.String()),
-	canResume: Type.Boolean({
-		description: "Direct-parent authority only; current admission and exited-session checks still apply.",
-	}),
+	canResume: Type.Boolean(),
 	kind: Type.Literal("started"),
 	id: Type.String(),
 	name: Type.String(),
 	agent: Type.String(),
-	model: Type.String({ description: "The model it was launched on." }),
-	finishedModel: Type.Optional(
-		Type.String({ description: "The model its result came from, read from its session file; done only." }),
-	),
+	model: Type.String(),
+	finishedModel: Type.Optional(Type.String()),
 	thinking: Type.String(),
 	autoExit: Type.Boolean(),
-	resumedFrom: Type.Optional(Type.String({ description: "The delegation whose session this one reopened." })),
+	resumedFrom: Type.Optional(Type.String()),
 	windowId: Type.String(),
 	windowName: Type.String(),
-	windowSession: Type.Optional(
-		Type.String({ description: "The tmux session its window is in now; absent when the window is gone." }),
-	),
-	cwd: Type.Optional(
-		Type.String({ description: "The directory its window opened in; absent for records from before it was kept." }),
-	),
-	sessionDir: Type.Optional(Type.String({ description: "The session-storage directory it was told to use." })),
+	windowSession: Type.Optional(Type.String()),
+	cwd: Type.Optional(Type.String()),
+	sessionDir: Type.Optional(Type.String()),
 	workspace: Type.Optional(WorkspaceSchema),
 	workspaceSnapshot: WorkspaceSnapshotSchema,
-	state: Type.Union(
-		STARTED_STATES.map((state) => Type.Literal(state)),
-		{
-			description:
-				"running: window open, no result. done: a result arrived (see status, envelopePath). gone: the window went with no result; a late reply makes it done. closed: delegation_close recorded it. window-closed: the window is gone. unknown: tmux could not be asked. done and closed are final, though a later delegation_resume continues one as a new delegation; gone and window-closed turn done if a late reply arrives.",
-		},
-	),
+	state: Type.Union(STARTED_STATES.map((state) => Type.Literal(state))),
 	closed: Type.Boolean(),
 	closedWithoutResult: Type.Boolean(),
-	status: Type.Optional(Type.String({ description: "The result envelope's status: done, failed or stopped." })),
+	status: Type.Optional(Type.String()),
 	envelopePath: Type.Optional(Type.String()),
 	sessionPath: Type.Optional(Type.String()),
-	lastActiveAt: Type.Optional(
-		Type.String({ description: "ISO time the session file was last written; running only." }),
-	),
+	lastActiveAt: Type.Optional(Type.String()),
 });
 
 const DelegationSchema = Type.Union([StartedSchema, AttemptSchema]);
@@ -297,10 +281,8 @@ function statusTool(results: Results, tmux: TmuxClient, readingErrors: () => Rea
 		name: "delegation_status",
 		label: "Delegation status",
 		description:
-			"This session’s descendant delegations, scoped to its own subtree. Parent/root/depth and stable session ids identify ownership; only a direct parent may resume a child. Shared accounting does not acknowledge result processing. Each delegation is reported as running (the window is open and no result has arrived yet), done (with the result envelope's status) or closed (closed with delegation_close, or its window is gone). A delegation whose window went with no reply is reported closed without a result until a late reply makes it done. Call it to check on a delegation that seems stuck or to find its files; a result arrives as a message on its own, so there is no need to call it to wait for one. Names the delegation id, agent, session name, model, thinking, window, working directory, delegate session path and result envelope path. A running delegation also shows when its session file was last written; a long gap may mean it is stuck but does not prove it. A delegate's window being open means it is connected, not that its task is unfinished or finished; only a result means done.",
-		parameters: Type.Object({
-			id: Type.Optional(Type.String({ description: "One delegation id; omit to report every delegation." })),
-		}),
+			"Report this session's descendant delegations, or one by id: state, window, model, paths and workspace. Results arrive as messages on their own, so call it only for a delegation that seems stuck or to find its files. An open window does not mean the task is unfinished; only a result means done. gone and window-closed turn done if a late reply arrives.",
+		parameters: Type.Object({ id: Type.Optional(Type.String()) }),
 		outputSchema: StatusSchema,
 		annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, ...CLOSED_WORLD },
 		async execute(
@@ -375,10 +357,8 @@ function closeTool(results: Results, tmux: TmuxClient, assertActive: () => void)
 		name: "delegation_close",
 		label: "Close delegation",
 		description:
-			"Explicitly close a descendant and its recorded subtree. Fences new child launches, kills only verified current tmux windows and retains worktrees, branches and session/result files. Any ancestor may close; only the direct parent may resume. Partial errors or unknown in-flight creates stay fenced and are reported for an explicit retry, never as successful closure.",
-		parameters: Type.Object({
-			id: Type.String({ description: "The delegation id to close." }),
-		}),
+			"Close a descendant and its recorded subtree: fence new launches and kill its verified windows, keeping worktrees, branches and session files. Check closed and complete; partial failures stay fenced for a retry.",
+		parameters: Type.Object({ id: Type.String() }),
 		outputSchema: CloseSchema,
 		// Kills only verified windows; repeats retry unresolved members and preserve confirmed facts.
 		annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, ...CLOSED_WORLD },

package/src/tree-close.ts

@@ -23,7 +23,7 @@ export const CloseSchema = Type.Object({
 	id: Type.String(),
 	windowId: Type.Optional(Type.String()),
 	windowName: Type.Optional(Type.String()),
-	closed: Type.Boolean({ description: "True only when every member is confirmed closed or never dispatched." }),
+	closed: Type.Boolean(),
 	complete: Type.Boolean(),
 	alreadyClosed: Type.Boolean(),
 	killed: Type.Boolean(),

package/src/workspace.ts

@@ -18,7 +18,7 @@ import {
 	ProjectTrustStore,
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { askGit, type GitLaunch, inspectGit, PathSummarySchema } from "./git.ts";
+import { askGit, type GitLaunch, inspectGit } from "./git.ts";
 import { localTrust, type TrustDecision, type TrustResolver, trustChoices } from "./trust-prompt.ts";
 import type { ManagedWorkspace } from "./worktree.ts";
 
@@ -41,69 +41,14 @@ export type DirectoryWorkspace = {
 	git: GitLaunch;
 };
 export type Workspace = DirectoryWorkspace | ManagedWorkspace;
-/** `GitPosition` as a schema. */
-export const PositionSchema = Type.Union([
-	Type.Object({ branch: Type.String(), detached: Type.Literal(false) }),
-	Type.Object({ branch: Type.Null(), detached: Type.Literal(true) }),
-]);
-
-/** `GitIdentity` as a schema. */
-export const IdentitySchema = Type.Object({
-	mainRoot: Type.String(),
-	commonDir: Type.String(),
-	checkoutRoot: Type.String(),
-});
-
-const CheckoutSchema = Type.Object({
-	kind: Type.Literal("git"),
-	identity: IdentitySchema,
-	position: PositionSchema,
-	head: Type.Union([Type.String(), Type.Null()]),
-	baseline: Type.Union([Type.String(), Type.Null()], {
-		description: "The commit checked out at launch; null when the checkout had no commit yet.",
-	}),
-});
-
-const CWD_DESCRIPTION = "The directory the delegate's window opened in.";
-
-/** `Workspace` as a schema, for the tools' structured outputs. */
-export const WorkspaceSchema = Type.Union([
-	Type.Object({
-		mode: Type.Union([Type.Literal("inherited"), Type.Literal("existing")]),
-		cwd: Type.String({ description: CWD_DESCRIPTION }),
-		git: Type.Union(
-			[
-				CheckoutSchema,
-				Type.Object({ kind: Type.Literal("non-git") }),
-				Type.Object({ kind: Type.Literal("unknown"), reason: Type.String() }),
-			],
-			{ description: "The checkout at launch: git, non-git, or unknown when Git could not be asked." },
-		),
-	}),
-	Type.Object({
-		mode: Type.Literal("managed"),
-		cwd: Type.String({ description: CWD_DESCRIPTION }),
-		git: CheckoutSchema,
-		sourceCwd: Type.String({ description: "The checkout the worktree was created from." }),
-		source: IdentitySchema,
-		createdBranch: Type.String({ description: "The branch created for the worktree, as originally named." }),
-		requestedBase: Type.String(),
-		baseCommit: Type.String({ description: "The commit the branch was created at." }),
-		sourceDirty: PathSummarySchema,
-	}),
-]);
-
-/** `WorktreePlan` as a schema: what an attempt intended. */
-export const WorktreePlanSchema = Type.Object({
-	sourceCwd: Type.String(),
-	source: IdentitySchema,
-	destination: Type.String(),
-	branch: Type.String(),
-	requestedBase: Type.String(),
-	baseCommit: Type.String(),
-	sourceDirty: PathSummarySchema,
-	trusted: Type.Boolean(),
-});
+/** `Workspace` as a schema for the tools' structured outputs: the discriminant and directory, the rest open to keep tool declarations short. */
+export const WorkspaceSchema = Type.Object(
+	{
+		mode: Type.Union([Type.Literal("inherited"), Type.Literal("existing"), Type.Literal("managed")]),
+		cwd: Type.String(),
+	},
+	{ additionalProperties: true },
+);
 
 /** Optional inputs some models fill with these instead of leaving them out. */
 const OMITTED = new Set(["", "null", "none", "false", "undefined"]);