pi-squire 0.16.0 → 0.18.0

package/CHANGELOG.md

@@ -6,6 +6,35 @@ follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [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
+
+- Nested launches and resumes no longer cap a child's tools to its direct
+  parent's. A nested child gets the tools its own agent file gives, as at top
+  level, and `session:launch` additions are no longer cut back afterwards; the
+  `allow_nested_delegation` list is the boundary. A read-only child started by
+  a writable parent now keeps tools such as `grep` that the parent lacks. The
+  "Nested tool ceiling" notices are gone. Tests that pinned the ceiling now pin
+  the new behaviour.
+
+### Added
+
+- `toolBundles` in `squire/settings.json` names shared tool lists; an agent's
+  `tools` field uses one as `$name`, for example `tools: [$readonly, pstack_models]`.
+  An unknown bundle, a `-$name` entry or an invalid setting disables the agent
+  that uses it.
+
 ## [0.16.0] - 2026-11-01
 
 ### Breaking
@@ -979,7 +1008,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.16.0...HEAD
+[Unreleased]: https://github.com/gvanderclay/pi-squire/compare/v0.18.0...HEAD
+[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
 [0.14.0]: https://github.com/gvanderclay/pi-squire/compare/v0.13.1...v0.14.0

package/README.md

@@ -177,7 +177,7 @@ 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
-explicit `tools` list, subject to the nested tool ceiling. Merely listing those
+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.
 
@@ -187,15 +187,12 @@ agent from the grant blocks future launches/resumes, not existing work.
 Trusted project agents still shadow global definitions. Each launching session
 keeps the existing throttled quota checks and shared reactive usage-limit marks.
 
-A nested launch or resume resolves its requested tools, `delegateTools` additions
-and automatic nesting grants, then restricts them to operations available to its
-direct parent. This includes active model-only operations and registered
-codemode/deferred tools, not just displayed schemas. Inactive direct tools and
-hidden tools are excluded. Patterns become exact names; removed tools and
-restricted patterns are reported in the launch/resume notice. The final
-registration allowlist is enforced after synchronous `session:launch`
-customization, so additions cannot register or reach tool names outside the
-direct parent’s ceiling. Top-level launch selection is unchanged.
+A nested child's tools are worked out as at top level, from its own agent file:
+its `tools` list, or, with no `tools` field, its direct parent's available
+tools (active ones plus codemode/deferred operations), plus `delegateTools` and
+the automatic nesting grant. They are not cut back to the parent's tools. The
+`allow_nested_delegation` list is the boundary: a coordinator that must not
+start a child with more tools lists only children whose agent files give fewer.
 
 Each agent keeps its own permission policy; squire does not inherit or compare
 effective policies. A granting agent with a `permission:` map (even `{}`) warns
@@ -203,7 +200,7 @@ when a listed child lacks one; `true` checks all applicable roster agents.
 This is only a heuristic warning, not authorization or proof of lesser privilege.
 Permission policy parsing/enforcement remains the permission provider’s job.
 Tool-name restrictions and configuration permission rules are not filesystem
-isolation: tools such as bash can write files or start processes. The ceiling
+isolation: tools such as bash can write files or start processes. A tool list
 bounds tool names, not arbitrary extension code or the implementation an
 extension registers under an allowed name. Rules asking
 before changes to agent/squire configuration cannot promise interception of
@@ -354,21 +351,21 @@ Only the **direct parent** may resume a child. Ancestor visibility grants no
 resume authority; forked/cloned/copied history with a new Pi id grants none.
 Return to the original parent. Identity is read from exact-id durable state,
 written before launch; inherited launch environment cannot assign a new session
-to the old tree. Current allowlists, depth, caps, callable-tool ceiling and
+to the old tree. Current allowlists, depth, caps and
 directory/source trust still apply to resume, including its picker. A live
 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
@@ -387,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
@@ -397,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.
@@ -419,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`:
 
@@ -932,10 +946,10 @@ optional, and the [first-use example](#first-use) is a complete agent file:
 | `display_name` | Shown instead of the name on the delegate card, in `/delegates` and in the window title (`<display_name>-<label>`). The agent is still called by its name. It may hold only ASCII letters, digits, `-` and `_`; any other value (a space, `#`, `.`, a non-ASCII letter, or an empty value) makes the file invalid, so the agent is disabled. |
 | `model` | One model: `provider/id` or an alias such as `sonnet`, passed to the child's `--model` unchanged, so Pi resolves it to one model. A `*` pattern makes the file invalid. Absent means the parent session's current model. |
 | `thinking` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh` or `max`. Absent means the parent session's level; an unknown value is dropped with a warning and the parent's level applies. Pi clamps the level to the model. |
-| `tools` | The delegate's tools (see below): tool names for exactly those, or only `-name` entries for the parent session's current tools less those. Absent means the parent session's current tools; empty (`tools:` or `tools: []`) means no tools except the `delegateTools` setting. MCP tools follow the selection like any other. |
+| `tools` | The delegate's tools (see below): tool names and `$bundle` entries for exactly those, or only `-name` entries for the parent session's current tools less those. Absent means the parent session's current tools; empty (`tools:` or `tools: []`) means no tools except the `delegateTools` setting. MCP tools follow the selection like any other. |
 | `fallback` | Models to try, in order, when `model` is usage-limited (see [Usage limits](#usage-limits)). Each entry is one model, like `model`; a `*` pattern, or a YAML list entry holding a comma, makes the file invalid. A comma-separated line (`fallback: a, b`) is two entries. |
 | `auto_exit` | `true` or `false`, default `true`; see [Auto-exit](#auto-exit). |
-| `allow_nested_delegation` | Unreleased: `true` or a YAML list of exact child agent names; grants nested delegation below `maxDepth`, subject to the parent tool ceiling (see [Nested delegation](#nested-delegation-unreleased)). Absent, false or an empty list grants none. Malformed values disable the agent; unavailable names warn. |
+| `allow_nested_delegation` | Unreleased: `true` or a YAML list of exact child agent names; grants nested delegation below `maxDepth` (see [Nested delegation](#nested-delegation-unreleased)). Absent, false or an empty list grants none. Malformed values disable the agent; unavailable names warn. |
 | `prompt_mode` | `append` (the default) wraps the body in `<agent_instructions>` and `</agent_instructions>` lines; `replace` adds the body unwrapped. An empty body adds nothing either way. |
 | `enabled` | `false` leaves the agent out. A project file with `enabled: false` hides a global agent of the same name in that project. |
 | `locked` | `true`, or a list of `model` and `thinking`. A call to `delegate`, `/delegate` or a resume that passes a locked field does not get it: the agent's value is used (the parent's when the file sets none) and the result says which agent locked which field. Passing the agent's own value is the same as passing nothing: no notice, and its fallbacks still apply. A resume of a locked field runs on the file's value as it is now, not on what the delegate last ran on. `true` locks the fields the file sets. |
@@ -973,11 +987,10 @@ loadable by `tool_search`, whatever its exposure. Pi filters MCP tools by
 such entry pi-squire adds the entry `mcp__`, which names no tool; an empty
 selection is `--no-tools`, which removes MCP tools too. To give a delegate an
 MCP server's tools, name them, for example `mcp__docs__*`. An extension that
-turns tools on at run time can still add only tools the list allows. Top-level tool names
-are not checked against the parent's tools: normal Pi extension discovery
-or `session:launch` customization can provide tools in the child. Nested launches
-and resumes instead apply the direct parent’s callable-tool ceiling after all
-selection and customization, as described above; this is not filesystem isolation.
+turns tools on at run time can still add only tools the list allows. Tool names
+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
@@ -988,13 +1001,31 @@ selection and customization, as described above; this is not filesystem isolatio
   except the `delegateTools` entries. With none of those either, it starts
   with `--no-tools`.
 - A `tools` list of tool names: exactly those tools, plus the
-  `delegateTools` entries.
+  `delegateTools` entries. A `$name` entry stands for the tools of that
+  bundle in the `toolBundles` setting (see below).
 - A `tools` list of only `-name` entries (`tools: -bash, -write`): the
   parent's tools, as with no `tools` field, less those, plus the
   `delegateTools` entries. A `-name` entry may be a `*` pattern
   (`-mcp__docs__*`).
-- A `+name` entry, or tool names and `-name` entries in one list, make the
-  file invalid, and the agent is disabled (see below).
+- A `+name` entry, a `-$name` entry, a `$name` entry naming no bundle, or
+  tool names and `-name` entries in one list, make the file invalid, and the
+  agent is disabled (see below).
+
+`toolBundles` in `<agent dir>/squire/settings.json` names tool lists that
+several agents share:
+
+```json
+{ "toolBundles": { "readonly": ["read", "grep", "find", "ls"] } }
+```
+
+An agent then writes `tools: [$readonly, pstack_models]`, which reads as
+`read, grep, find, ls, pstack_models`; a name listed twice counts once. A
+bundle name is letters, digits, `_` or `-`; each entry is one tool name or
+`*` pattern, with no comma and no leading `+`, `-` or `$`, so bundles do not
+nest. A bundle carries tools only, not permission rules. The setting is read
+with the roster. A setting that is not an object of such lists disables every
+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
@@ -1015,9 +1046,7 @@ the `delegateTools` setting, in `<agent dir>/squire/settings.json` beside
 
 Each entry, a tool name or `*` pattern, is added to every delegate's tools,
 whether they come from its agent's `tools` or from the parent (after any
-`-name` entries are taken off). Top-level launches pass these to `--tools`
-unchanged; nested launches/resumes resolve and cap them by the direct parent’s
-available tools. The setting
+`-name` entries are taken off), and passed to `--tools` unchanged. The setting
 is empty by default, is read at each launch and resume, and a value that is
 not a list of names, or an entry that holds a comma or starts with `+` or
 `-`, refuses every launch with an error naming the file, before the task is sent or a window
@@ -1064,8 +1093,8 @@ add one.
 
 `<agent dir>/squire/` holds the optional parent guidance file and
 `settings.json` (`maxDepth`, `maxConcurrentDelegates`, `maxDelegatesPerRoot`,
-`windowPlacement`, `worktreeRoot`, `delegateTools`, `delegateWidgetPlacement` and
-`delegateWidgetMaxEntries`); the
+`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
 `squire_parent_delegation` system-prompt section before each new run, including
@@ -1274,8 +1303,8 @@ success or cancellation envelope.
 
 Once the explicit operation is complete, a legitimate direct-parent resume can
 supersede that session's completed fence as a **new lifetime-counted delegation**.
-It still passes current authority/owner, chain, depth, grants, caps, tool-ceiling
-and trust checks. Failed pre-dispatch resumes leave the old fence effective.
+It still passes current authority/owner, chain, depth, grants, caps and trust
+checks. Failed pre-dispatch resumes leave the old fence effective.
 Closed descendants remain canceled; resuming a coordinator does not revive them.
 An unresolved active close cannot be bypassed by resume.
 
@@ -1584,7 +1613,7 @@ and it resumes as the command does.
   receives it once its mailbox starts. If the send fails, the new window is
   killed and nothing is recorded.
 - Only its direct parent may resume it, preserving the original root/depth.
-  The current parent grant, depth/cap/tool-ceiling/trust checks are reapplied.
+  The current parent grant, depth/cap/trust checks are reapplied.
   A chain resumes from its newest local/shared delegation; older records and
   copied fork/clone history are refused, naming the owner or newest record.
 - It is refused, before anything is sent or opened, unless: the delegation is a
@@ -1954,8 +1983,8 @@ Other extensions may rely on:
 - the agent file's frontmatter keys and its locations,
   `<agent dir>/agents/<name>.md` and, in a trusted project,
   `<cwd>/.pi/agents/<name>.md`;
-- the `maxDepth`, `maxConcurrentDelegates`, `maxDelegatesPerRoot`, `delegateTools`,
-  `windowPlacement`, `worktreeRoot`, `delegateWidgetPlacement` and
+- the `maxDepth`, `maxConcurrentDelegates`, `maxDelegatesPerRoot`, `delegateTools`, `toolBundles`,
+  `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.16.0",
+	"version": "0.18.0",
 	"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

@@ -11,7 +11,8 @@
 // holding a comma, makes the file invalid; absent `model` means the parent's),
 // `thinking` (absent or unknown means the parent's level), `tools` (the
 // delegate's complete tool list; absent means the parent's tools, empty means
-// none; a list entry holding a comma makes the file invalid), `auto_exit` (default true),
+// none; a list entry holding a comma makes the file invalid; a `$name` entry
+// stands for that `toolBundles` bundle's tools), `auto_exit` (default true),
 // `prompt_mode` (`append`, the default, or `replace`), `enabled` (false leaves
 // the agent out) and `locked` (true, or a list of `model` and `thinking`). Any
 // other key is ignored, left for whatever else reads the file. The body is the
@@ -21,7 +22,8 @@ import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 
 import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
-import { toolMatches } from "./tool-ceiling.ts";
+import { type Bundles, expandBundles, toolBundles } from "./tool-bundles.ts";
+import { toolMatches } from "./tool-names.ts";
 
 /** The levels `pi --thinking` accepts. */
 export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
@@ -106,7 +108,7 @@ const field = (frontmatter: Record<string, unknown>, key: string): string | unde
 type Parsed = { agent?: Agent; invalid?: string; notes: string[] };
 
 /** Parse one agent file; no agent, with why it is invalid when it is, when it cannot be an agent or is disabled. */
-function parseAgent(name: string, path: string, text: string): Parsed {
+function parseAgent(name: string, path: string, text: string, bundles: Bundles): Parsed {
 	let frontmatter: unknown;
 	let body: string;
 	try {
@@ -130,7 +132,7 @@ function parseAgent(name: string, path: string, text: string): Parsed {
 			invalid: `${path} has allow_nested_delegation that is not true, false or a list of agent names`,
 			notes: [],
 		};
-	const launch = toolsField(path, fields);
+	const launch = toolsField(path, fields, bundles);
 	if ("invalid" in launch) return { ...launch, notes: [] };
 	const model = field(fields, "model");
 	const fallback = toolList(fields.fallback);
@@ -272,14 +274,15 @@ function lockedFields(
 }
 
 /**
- * The `tools` field: tool names (`*` patterns allowed) are the whole list;
- * only `-name` entries take those off the parent's tools. A `+name` entry,
- * names and `-name` entries mixed, or a YAML list entry holding a comma make
- * the file invalid.
+ * The `tools` field: tool names (`*` patterns allowed) and `$bundle` entries
+ * are the whole list; only `-name` entries take those off the parent's tools.
+ * A `+name` entry, names and `-name` entries mixed, an unknown bundle, or a
+ * YAML list entry holding a comma make the file invalid.
  */
 function toolsField(
 	path: string,
 	frontmatter: Record<string, unknown>,
+	bundles: Bundles,
 ): { tools?: string[]; toolsExcept: string[] } | { invalid: string } {
 	// `tools:` with no value is YAML null: present and empty, unlike an absent field.
 	const tools = Object.hasOwn(frontmatter, "tools") && frontmatter.tools === null ? [] : toolList(frontmatter.tools);
@@ -298,8 +301,13 @@ function toolsField(
 		return {
 			invalid: `${path} has tools entry ${JSON.stringify(plus)}: +name entries are not accepted; list every tool by name, or only -name entries to take tools off the parent's`,
 		};
+	const minusBundle = tools.find((name) => name.startsWith("-$"));
+	if (minusBundle !== undefined)
+		return {
+			invalid: `${path} has tools entry ${JSON.stringify(minusBundle)}: a bundle cannot be taken off; take its tools off by name`,
+		};
 	const minus = tools.filter((name) => name.startsWith("-"));
-	if (minus.length === 0) return { tools, toolsExcept: [] };
+	if (minus.length === 0) return expandBundles(path, tools, bundles);
 	if (minus.length < tools.length)
 		return {
 			invalid: `${path} has tools that mix tool names with -name entries; list every tool by name, or only -name entries to take tools off the parent's`,
@@ -371,6 +379,7 @@ export function readRoster(agentDir: string, projectDir?: string): Roster {
 	const agents: Agent[] = [];
 	const disabled: Disabled[] = [];
 	const warnings: string[] = [];
+	const bundles = toolBundles(agentDir);
 	const retired = join(agentDir, "squire", "agents");
 	if (existsSync(retired))
 		warnings.push(
@@ -393,7 +402,7 @@ export function readRoster(agentDir: string, projectDir?: string): Roster {
 			disable(name, path, `${path} could not be read (${(err as Error).message})`);
 			continue;
 		}
-		const { agent, invalid, notes } = parseAgent(name, path, text);
+		const { agent, invalid, notes } = parseAgent(name, path, text, bundles);
 		warnings.push(...notes);
 		if (agent !== undefined) agents.push(agent);
 		else if (invalid !== undefined) disable(name, path, invalid);

package/src/index.ts

@@ -78,7 +78,7 @@ import { pickResume } from "./resume-picker.ts";
 import { ownedAPI, SessionOwner, sessionIsOwned } from "./session-owner.ts";
 import { registerTaskReplies } from "./task-replies.ts";
 import { createTmuxClient, type OpenedWindow, requireTmuxVersion, type TmuxClient, WindowOpenError } from "./tmux.ts";
-import { availableTools, enforceToolCeiling } from "./tool-ceiling.ts";
+import { availableTools } from "./tool-names.ts";
 import { createTracking, toolResult } from "./tracking.ts";
 import { treeNotice } from "./tree-notice.ts";
 import {
@@ -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,
@@ -1044,22 +1044,6 @@ export default function delegate(
 		for (const key of ["parent", "root", "depth", "chain"] as const)
 			Object.defineProperty(payload, key, { writable: false, configurable: false });
 		pi.events.emit(LAUNCH, payload);
-		if (identity.current()) {
-			const prefix = parentCommand().length;
-			const args = payload.args.slice(prefix);
-			enforceToolCeiling({
-				args,
-				available: availableTools(pi).filter(
-					(name) => grantsNesting(start.agent, own.depth) || !DELEGATION_TOOLS.has(name),
-				),
-				registered: pi.getAllTools().map((tool) => tool.name),
-				cwd,
-				agentDir: payload.env.PI_CODING_AGENT_DIR,
-				trusted,
-				notices: start.notices,
-			});
-			payload.args.splice(prefix, payload.args.length - prefix, ...args);
-		}
 		const token: Reservation = { root: own.root, id };
 		bindTree(token, { windowName: name, cwd, workspace });
 		dispatchTree(token);
@@ -1163,11 +1147,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);
@@ -1382,7 +1366,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) => {

package/src/tool-bundles.ts

@@ -0,0 +1,84 @@
+// Tool bundles: named tool lists in `<agent dir>/squire/settings.json`
+// `toolBundles`, which an agent's `tools` field names as `$name`. A bundle is
+// only shorthand for tool names; it carries no permission rules.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** A bundle name: the same rule as an agent name. */
+const NAME = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+
+/**
+ * Replace each `$name` entry with the tools of the `toolBundles` bundle it
+ * names, keeping the first of any repeated name. An unknown bundle, or any
+ * bundle while the setting is invalid, makes the file invalid.
+ */
+export function expandBundles(
+	path: string,
+	tools: string[],
+	bundles: Bundles,
+): { tools: string[]; toolsExcept: string[] } | { invalid: string } {
+	const expanded: string[] = [];
+	for (const entry of tools) {
+		if (!entry.startsWith("$")) {
+			expanded.push(entry);
+			continue;
+		}
+		const names = bundles.names.get(entry.slice(1));
+		if (names === undefined)
+			return {
+				invalid:
+					bundles.problem === undefined
+						? `${path} has tools entry ${JSON.stringify(entry)}, but toolBundles in ${bundles.file} defines no bundle ${JSON.stringify(entry.slice(1))}`
+						: `${path} has tools entry ${JSON.stringify(entry)}, but ${bundles.problem}`,
+			};
+		expanded.push(...names);
+	}
+	return { tools: [...new Set(expanded)], toolsExcept: [] };
+}
+
+/** The `toolBundles` setting: tool lists by bundle name, or why the setting cannot be used. */
+export type Bundles = { file: string; names: ReadonlyMap<string, readonly string[]>; problem?: string };
+
+/**
+ * The `toolBundles` setting in `<agent dir>/squire/settings.json`: named lists
+ * of tool names or `*` patterns an agent's `tools` field names as `$name`.
+ * Empty when the file or setting is absent. A setting that is not an object of
+ * name lists, or a bundle entry that holds a comma or starts with `+`, `-` or
+ * `$` (bundles do not nest), leaves no bundles and says why.
+ */
+export function toolBundles(agentDir: string): Bundles {
+	const file = join(agentDir, "squire", "settings.json");
+	const none = (problem?: string): Bundles => ({ file, names: new Map(), ...(problem ? { problem } : {}) });
+	let text: string;
+	try {
+		text = readFileSync(file, "utf8");
+	} catch {
+		return none();
+	}
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(text);
+	} catch {
+		return none(`${file} is not valid JSON, so its toolBundles cannot be read`);
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return none();
+	const value = (parsed as Record<string, unknown>).toolBundles;
+	if (value === undefined) return none();
+	const invalid = (why: string): Bundles => none(`toolBundles in ${file} is invalid: ${why}`);
+	if (typeof value !== "object" || value === null || Array.isArray(value))
+		return invalid("it must be an object of bundle names to lists of tool names");
+	const names = new Map<string, string[]>();
+	for (const [name, list] of Object.entries(value)) {
+		if (!NAME.test(name)) return invalid(`bundle name ${JSON.stringify(name)} is not letters, digits, _ or -`);
+		if (!Array.isArray(list) || !list.every((entry) => typeof entry === "string" && entry.trim() !== ""))
+			return invalid(`bundle ${JSON.stringify(name)} must be a list of tool names or patterns`);
+		const tools = list.map((entry: string) => entry.trim());
+		const bad = tools.find((tool) => tool.includes(",") || /^[+\-$]/.test(tool));
+		if (bad !== undefined)
+			return invalid(
+				`bundle ${JSON.stringify(name)} entry ${JSON.stringify(bad)} must be one tool name or pattern, with no comma and no leading +, - or $`,
+			);
+		names.set(name, tools);
+	}
+	return { file, names };
+}

package/src/tool-names.ts

@@ -0,0 +1,29 @@
+// Tool-name helpers shared by the roster and launch code.
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+/** Match Pi's tool-list glob: only * has special meaning. */
+export function toolMatches(pattern: string, name: string): boolean {
+	const source = pattern
+		.split("*")
+		.map((part) => part.replace(/[.+?^${}()|[\]\\]/g, "\\$&"))
+		.join(".*");
+	return new RegExp(`^${source}$`).test(name);
+}
+
+/**
+ * The operations this session can reach: active tools plus codemode and
+ * deferred ones, never hidden ones. A nested delegate with no `tools` field
+ * inherits these. Includes active model-only operations, though
+ * ctx.executeTool cannot call those.
+ */
+export function availableTools(pi: Pick<ExtensionAPI, "getActiveTools" | "getAllTools">): string[] {
+	const active = new Set(pi.getActiveTools());
+	return pi
+		.getAllTools()
+		.filter(
+			(tool) =>
+				tool.exposure !== "hidden" &&
+				(active.has(tool.name) || tool.exposure === "codemode" || tool.exposure === "deferred"),
+		)
+		.map((tool) => tool.name);
+}

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/tool-ceiling.ts

@@ -1,125 +0,0 @@
-// A nested launch is bounded by operations its direct parent can reach, not
-// by the schemas currently displayed. CLI registration filtering also covers
-// deferred tools and tools registered later by launch-time extensions.
-import { type Args, type ExtensionAPI, parseArgs, SettingsManager } from "@earendil-works/pi-coding-agent";
-
-/** Match Pi's tool-list glob: only * has special meaning. */
-export function toolMatches(pattern: string, name: string): boolean {
-	const source = pattern
-		.split("*")
-		.map((part) => part.replace(/[.+?^${}()|[\]\\]/g, "\\$&"))
-		.join(".*");
-	return new RegExp(`^${source}$`).test(name);
-}
-
-/** Includes active model-only operations, though ctx.executeTool cannot call those. */
-export function availableTools(pi: Pick<ExtensionAPI, "getActiveTools" | "getAllTools">): string[] {
-	const active = new Set(pi.getActiveTools());
-	return pi
-		.getAllTools()
-		.filter(
-			(tool) =>
-				tool.exposure !== "hidden" &&
-				(active.has(tool.name) || tool.exposure === "codemode" || tool.exposure === "deferred"),
-		)
-		.map((tool) => tool.name);
-}
-
-type CeilingInput = {
-	args: string[];
-	available: readonly string[];
-	registered?: readonly string[];
-	cwd: string;
-	agentDir: string;
-	trusted: boolean;
-	notices: string[];
-};
-
-function requestedTools(parsed: Args, input: CeilingInput): string[] {
-	const requested = parsed.tools ?? [];
-	if (!requested.some((name) => name.startsWith("+") || name.startsWith("-"))) return requested;
-	// Pi modifiers replace the earlier --tools selection and modify the
-	// child's defaults. Use Pi's trusted settings reader, not the parent's defaults.
-	const defaults =
-		parsed.noTools || parsed.noBuiltinTools
-			? []
-			: (SettingsManager.create(input.cwd, input.agentDir, { projectTrusted: input.trusted }).getDefaultTools() ?? [
-					"read",
-					"bash",
-					"edit",
-					"write",
-				]);
-	const selected = new Set(defaults);
-	for (const entry of requested) {
-		if (entry.startsWith("+")) selected.add(entry.slice(1));
-		else selected.delete(entry.slice(1));
-	}
-	return [...selected];
-}
-
-function ceilingNotice(input: CeilingInput, requested: string[], exclusions: string[]): void {
-	const { available } = input;
-	const removed = [
-		...new Set([
-			...requested.filter((pattern) => pattern !== "mcp__" && !pattern.includes("*") && !available.includes(pattern)),
-			...(input.registered ?? []).filter(
-				(name) => !available.includes(name) && requested.some((pattern) => toolMatches(pattern, name)),
-			),
-		]),
-	].filter((name) => !exclusions.some((pattern) => toolMatches(pattern, name)));
-	// Child-only and future registrations cannot be enumerated in the parent.
-	const bounded = [...new Set(requested.filter((pattern) => pattern.includes("*")))];
-	if (!removed.length && !bounded.length) return;
-	const parts = ["Nested tool ceiling:"];
-	if (removed.length) parts.push(`removed unavailable tools ${removed.join(", ")}.`);
-	if (bounded.length)
-		parts.push(`Restricted patterns ${bounded.join(", ")} to exact tools available to the direct parent.`);
-	input.notices.push(parts.join(" "));
-}
-
-/** Find an option terminator, not a -- token consumed as another flag’s value. */
-function optionBoundary(args: string[]): number {
-	let marker = "--squire-ceiling-boundary";
-	while (args.includes(marker)) marker += "-";
-	for (const [index, arg] of args.entries()) {
-		if (arg === "--" && !parseArgs([...args.slice(0, index + 1), marker]).unknownFlags.has(marker.slice(2)))
-			return index;
-	}
-	return args.length;
-}
-
-function exactName(name: string): boolean {
-	return !!name && name.trim() === name && !name.includes("*") && !name.includes(",") && !/^[+-]/.test(name);
-}
-
-/**
- * Resolve the final customized CLI selection, then pin an exact registration
- * allowlist. Run after all synchronous session:launch listeners, before spawn.
- * args excludes the executable/launcher prefix. Unrelated args stay unchanged.
- */
-export function enforceToolCeiling(input: CeilingInput): void {
-	const { args, available } = input;
-	const parsed = parseArgs(args);
-	const errors = parsed.diagnostics.filter((item) => item.type === "error");
-	if (errors.length)
-		throw new Error(`invalid nested launch arguments: ${errors.map((item) => item.message).join("; ")}`);
-	const requested = requestedTools(parsed, input);
-	const exclusions = parsed.excludeTools ?? [];
-	const allowed = available.filter(
-		(name) =>
-			requested.some((pattern) => toolMatches(pattern, name)) &&
-			!exclusions.some((pattern) => toolMatches(pattern, name)),
-	);
-	// Never turn a wildcard in a registered name into a grant pattern.
-	if (!allowed.every(exactName))
-		throw new Error("cannot encode the parent's tool names as an exact nested tool ceiling");
-	ceilingNotice(input, requested, exclusions);
-	const entries = allowed.some((name) => name.startsWith("mcp__")) ? allowed : [...allowed, "mcp__"];
-	// --no-tools alone would leave a previous --tools value authoritative.
-	const final = allowed.length ? ["--tools", entries.join(",")] : ["--tools", "", "--no-tools"];
-	args.splice(optionBoundary(args), 0, ...final);
-	const effective = parseArgs(args).tools;
-	const expected = allowed.length ? entries : [];
-	if (!effective || effective.length !== expected.length || effective.some((name, index) => name !== expected[index]))
-		throw new Error("could not apply the nested tool ceiling to customized launch arguments");
-}