pi-squire 0.17.0 → 0.18.1

package/CHANGELOG.md

@@ -6,6 +6,32 @@ follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [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
+
+- New root companion sessions deliberately default to `<project>-delegates`
+  instead of `<project>-delegate-session`. Set `companionSuffix` in
+  `<agent dir>/squire/settings.json` to use another suffix, such as `playpen`.
+  Existing companions and saved identities keep their names, including for
+  nested launches and resumes.
+
 ## [0.17.0] - 2026-11-01
 
 ### Breaking
@@ -998,7 +1024,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.17.0...HEAD
+[Unreleased]: https://github.com/gvanderclay/pi-squire/compare/v0.18.1...HEAD
+[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
 [0.15.0]: https://github.com/gvanderclay/pi-squire/compare/v0.14.0...v0.15.0

package/README.md

@@ -358,14 +358,14 @@ same-id Squire owner and obsolete local/shared resume chains are refused.
 ## Where delegate windows open
 
 By default a delegate's window opens in a shared **project companion session**
-named `<project>-delegate-session` on your existing tmux server. The owning
+named `<project>-delegates` on your existing tmux server. The owning
 root Pi session's project chooses it, not the parent tmux session or the
 delegate's working directory. Launching into another repository or creating a
 worktree there still uses the root's companion; resuming a delegate does too.
 
 Nested launches inherit the original root project: A → coordinator in B →
 worker in C all select A's companion. The preferred base name (for example,
-`A-delegate-session`) is saved as `rootPlacement` in the existing durable
+`A-delegates`) is saved as `rootPlacement` in the existing durable
 delegation identity and shared tree records, not recomputed from B/C or the
 containing tmux session. Reopening the **same** coordinator session without its
 launch environment restores that preference; it can launch or directly resume
@@ -384,7 +384,7 @@ uses the root working-directory basename instead.
 Project names preserve ASCII letters (including case), digits, hyphens and
 underscores. Runs of other characters become one hyphen, edge hyphens are
 trimmed, and an empty name becomes `project`: `Client API` uses
-`Client-API-delegate-session`.
+`Client-API-delegates`.
 
 Multiple roots share a companion even across parent tmux sessions. Distinct
 paths with the same basename, separate clones named alike, and names that
@@ -394,12 +394,13 @@ each root.
 
 pi-squire verifies the tmux session option `@squire-companion` before reusing
 an occupied name. An unmarked session is left untouched; numbered alternatives
-start at `<project>-delegate-session-2`, skipping unmarked alternatives too.
+start at `<project>-<suffix>-2`, skipping unmarked alternatives too.
 Later launches reuse an existing managed alternative even if a lower name
 becomes free. Unexpected duplicate managed candidates use the first in numeric
-order, without moving windows or repairing sessions. Existing legacy companions
-and live windows are neither renamed nor migrated; only new launches and
-resumes use project naming.
+order, without moving windows or repairing sessions. Existing companions,
+live windows and saved identities keep their names, including the former
+`<project>-delegate-session` default. Nested launches and resumes retain the
+saved preference; companions are not renamed or migrated.
 
 - The session is created on demand, by the launch that needs it, and tmux
   removes it with its last window, so it does not outlive its delegates.
@@ -416,6 +417,22 @@ resumes use project naming.
   up each time, so it follows a window you move to another session, which is
   still found, closed and resumed.
 
+To use a different suffix, set `companionSuffix` in
+`<agent dir>/squire/settings.json`:
+
+```json
+{ "companionSuffix": "playpen" }
+```
+
+This names a new root's companion `<project>-playpen`. The default suffix is
+`delegates`. A suffix must contain 1 to 32 ASCII letters, digits, underscores
+or hyphens, with no leading or trailing hyphen. It cannot be entirely numeric
+or end in a hyphen followed by digits, such as `2` or `x-10`, because those
+names overlap with numbered alternatives. An invalid suffix refuses the launch
+with an error naming the file, before the task is sent or a window opens.
+The suffix is read with `windowPlacement` at launch. It does not replace a
+saved root preference for nested launches or resumes.
+
 To open windows in your own session, as before, set `windowPlacement` in
 `<agent dir>/squire/settings.json`, beside `worktreeRoot`:
 
@@ -1046,14 +1063,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
@@ -1076,7 +1093,7 @@ add one.
 
 `<agent dir>/squire/` holds the optional parent guidance file and
 `settings.json` (`maxDepth`, `maxConcurrentDelegates`, `maxDelegatesPerRoot`,
-`windowPlacement`, `worktreeRoot`, `delegateTools`, `toolBundles`,
+`windowPlacement`, `companionSuffix`, `worktreeRoot`, `delegateTools`, `toolBundles`,
 `delegateWidgetPlacement` and `delegateWidgetMaxEntries`); the
 agents live in `<agent dir>/agents/` (see [Agents](#agents)).
 `delegation_prompt.md` is Markdown, inserted unchanged as the
@@ -1967,7 +1984,7 @@ Other extensions may rely on:
   `<agent dir>/agents/<name>.md` and, in a trusted project,
   `<cwd>/.pi/agents/<name>.md`;
 - the `maxDepth`, `maxConcurrentDelegates`, `maxDelegatesPerRoot`, `delegateTools`, `toolBundles`,
-  `windowPlacement`, `worktreeRoot`, `delegateWidgetPlacement` and
+  `windowPlacement`, `companionSuffix`, `worktreeRoot`, `delegateWidgetPlacement` and
   `delegateWidgetMaxEntries` settings in
   `<agent dir>/squire/settings.json`;
 - the optional `<agent dir>/squire/delegation_prompt.md` file and the

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-squire",
-	"version": "0.17.0",
+	"version": "0.18.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/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

@@ -100,7 +100,7 @@ import { registerTrustControl } from "./trust-control.ts";
 import { createProactive, createUsageClient, type Proactive, type UsageClient } from "./usage.ts";
 import { registerDelegateWidget } from "./widget.ts";
 import { registerActivityRuntime } from "./widget-activity-runtime.ts";
-import { assertRootPlacement, placementProject, type WindowPlacement, windowPlacement } from "./window-placement.ts";
+import { assertRootPlacement, placementProject, type WindowPlacement, windowSettings } from "./window-placement.ts";
 import {
 	normalizeWorkspaceValue,
 	prepareDirectory,
@@ -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");
 }
 
@@ -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,
@@ -1147,11 +1125,11 @@ export default function delegate(
 		if (!tmux.insideTmux()) throw new Error(NOT_IN_TMUX);
 		await requireTmuxVersion(tmux);
 		// Read once, before anything is created or mailed; the launch keeps these values.
-		const placement = windowPlacement(getAgentDir());
+		const { placement, companionSuffix } = windowSettings(getAgentDir());
 		const parentIdentity = identity.current();
 		const project = parentIdentity
 			? { companion: parentIdentity.rootPlacement, notices: [] }
-			: placementProject(ctx.cwd);
+			: placementProject(ctx.cwd, companionSuffix);
 		assertRootPlacement(project.companion);
 		const own = identity.child(start.agent, ctx, project.companion);
 		if (parentIdentity) assertParentPlacement(readTree(own.root), own);
@@ -1366,7 +1344,7 @@ export default function delegate(
 		delegateSchema: DelegateSchema,
 		notInTmux: NOT_IN_TMUX,
 		startPolling: tracking.startPolling,
-		placement: () => windowPlacement(getAgentDir()),
+		placement: () => windowSettings(getAgentDir()).placement,
 		roster: rosterFor,
 		admit: (agent, ctx) => admit(agent, currentRoster(ctx)),
 		authorize: (id, ctx) => {
@@ -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/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/window-placement.ts

@@ -1,6 +1,6 @@
 // Call-time choice of where delegate windows open. `companion` (the default)
-// opens them in a shared project session; `current`
-// opens them in the parent's own session, as before. Read from
+// opens them in a shared project session named `<project>-<companionSuffix>`
+// (default suffix `delegates`); `current` opens in the parent's own session. Read from
 // `<agent dir>/squire/settings.json` at every launch, like `worktreeRoot`.
 import { readFileSync } from "node:fs";
 import { basename, join } from "node:path";
@@ -9,21 +9,25 @@ import { inspectGit } from "./git.ts";
 
 export type WindowPlacement = "companion" | "current";
 
+const DEFAULT_SUFFIX = "delegates";
+const safeName = /^[A-Za-z0-9_](?:[A-Za-z0-9_-]*[A-Za-z0-9_])?$/;
+const numberedEnding = /(^|-)[0-9]+$/;
+
 /** A preferred base, never a selected numbered companion or a tmux locator. */
 export function assertRootPlacement(value: unknown): asserts value is string {
-	if (typeof value !== "string" || !/^[A-Za-z0-9_](?:[A-Za-z0-9_-]*[A-Za-z0-9_])?-delegate-session$/.test(value))
+	if (typeof value !== "string" || !safeName.test(value) || !value.includes("-") || numberedEnding.test(value))
 		throw new Error(
 			"invalid or missing rootPlacement in delegation identity; original root companion preference is required",
 		);
 }
 
 /** The owning root's project, never the delegate's chosen working directory. */
-export function placementProject(cwd: string): { companion: string; notices: string[] } {
+export function placementProject(cwd: string, suffix = DEFAULT_SUFFIX): { companion: string; notices: string[] } {
 	const git = inspectGit(cwd);
 	const project = basename(git.kind === "git" ? git.identity.mainRoot : cwd);
 	const normalized = project.replace(/[^A-Za-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "") || "project";
 	return {
-		companion: `${normalized}-delegate-session`,
+		companion: `${normalized}-${suffix}`,
 		notices:
 			git.kind === "unknown"
 				? [
@@ -38,19 +42,32 @@ export function placementProject(cwd: string): { companion: string; notices: str
  * This reader defaults malformed/unreadable files to companion; mandatory
  * tree-cap admission separately refuses those files for every launch/resume.
  */
-export function windowPlacement(agentDir: string): WindowPlacement {
+export function windowSettings(agentDir: string): { placement: WindowPlacement; companionSuffix: string } {
 	const file = join(agentDir, "squire", "settings.json");
 	let parsed: unknown;
 	try {
 		parsed = JSON.parse(readFileSync(file, "utf8"));
 	} catch {
-		return "companion";
+		return { placement: "companion", companionSuffix: DEFAULT_SUFFIX };
 	}
-	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return "companion";
-	const value = (parsed as Record<string, unknown>).windowPlacement;
-	if (value === undefined || value === "companion") return "companion";
-	if (value === "current") return "current";
-	throw new Error(
-		`invalid window placement settings ${file}: windowPlacement must be "companion" or "current", not ${JSON.stringify(value)}`,
-	);
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+		return { placement: "companion", companionSuffix: DEFAULT_SUFFIX };
+	const { windowPlacement: placement = "companion", companionSuffix = DEFAULT_SUFFIX } = parsed as Record<
+		string,
+		unknown
+	>;
+	if (placement !== "companion" && placement !== "current")
+		throw new Error(
+			`invalid window placement settings ${file}: windowPlacement must be "companion" or "current", not ${JSON.stringify(placement)}`,
+		);
+	if (
+		typeof companionSuffix !== "string" ||
+		companionSuffix.length > 32 ||
+		!safeName.test(companionSuffix) ||
+		numberedEnding.test(companionSuffix)
+	)
+		throw new Error(
+			`invalid window placement settings ${file}: companionSuffix must be 1 to 32 ASCII letters, digits, underscores or hyphens, with no edge hyphen or numeric final segment, not ${JSON.stringify(companionSuffix)}`,
+		);
+	return { placement, companionSuffix };
 }

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"]);