pi-squire 0.14.0 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-squire",
-	"version": "0.14.0",
+	"version": "0.16.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",
@@ -54,8 +54,9 @@
 		"@earendil-works/pi-ai": "1.3.0",
 		"@earendil-works/pi-coding-agent": "1.3.0",
 		"@earendil-works/pi-tui": "1.3.0",
-		"@types/node": "26.6.3",
-		"typebox": "1.3.27",
+		"@types/node": "26.6.5",
+		"pi-session-mail": "0.6.0",
+		"typebox": "1.4.3",
 		"typescript": "7.0.2"
 	}
 }

package/src/agents.ts

@@ -1,18 +1,27 @@
-// The parent's agent roster: `<agent dir>/squire/agents/<name>/AGENT.md`, read at
-// call time so a new agent is usable without a reload. Frontmatter carries
-// `description`, `model` and `thinking`, and optionally `auto-exit` (default
-// true) and `exclude-tools` (tools the delegate goes without, passed to its Pi
-// as `--exclude-tools`; each must be a tool the parent session has), `tools`
-// (the delegate's complete tool allowlist, passed as `--tools`, not checked
-// against the parent) and `extensions` (extra extension paths for the
-// delegate only, each passed as `-e`; `~` expands, relative paths resolve
-// against the AGENT.md's directory, and a missing path leaves the agent out); the body
-// is the delegate's system prompt. A file that is missing or malformed is left out, with a warning.
-import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+// The parent's agent roster: one file per agent, `<name>.md`, in the agents
+// folders Pi agent tooling shares. `<agent dir>/agents/` holds the global
+// agents; `<cwd>/.pi/agents/` holds a project's, read only when the project is
+// trusted, and a project file replaces the global file of the same name. The
+// roster is read at call time, so a new agent is usable without a reload.
+//
+// Every frontmatter field is optional: `description` (default the name),
+// `display_name` (ASCII letters, digits, `-` and `_` only; anything else,
+// empty included, makes the file invalid), `model` and `fallback` (each one model, `provider/id` or an
+// alias, passed to the child's Pi unchanged; a `*` pattern, or a list entry
+// 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),
+// `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
+// delegate's instructions. A file that cannot be read as an agent is disabled:
+// left out, with a warning, and a call naming it is refused with the reason.
+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";
 
 /** The levels `pi --thinking` accepts. */
 export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
@@ -23,142 +32,281 @@ export function isThinking(value: string): value is Thinking {
 	return (THINKING_LEVELS as readonly string[]).includes(value);
 }
 
+/** The fields an agent file can lock against a call's override. */
+export const LOCKABLE = ["model", "thinking"] as const;
+
+export type Lockable = (typeof LOCKABLE)[number];
+
+/** How the body joins the delegate's prompt: wrapped in `<agent_instructions>`, or as it is. */
+export type PromptMode = "append" | "replace";
+
 /** An agent name is one safe path segment and one safe tmux window name. */
 const NAME = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
 
-/** `provider/id`; the id may itself contain slashes. */
-const MODEL = /^[^\s/]+\/\S+$/;
+/** A display name names a tmux window and a Pi session: ASCII letters, digits, `-` and `_` only. */
+const DISPLAY_NAME = /^[A-Za-z0-9_-]+$/;
 
 export type Agent = {
 	name: string;
+	/** Shown instead of the name on the delegate card, `/delegates` and the window title; from `display_name`, `[A-Za-z0-9_-]+`. */
+	displayName?: string;
 	description: string;
-	model: string;
-	thinking: Thinking;
-	/** Whether the delegate closes itself after a normal completion; `auto-exit`, default true. */
+	/** Passed to the child's `--model` unchanged; undefined means the parent's model. */
+	model?: string;
+	/** Undefined means the parent's level. */
+	thinking?: Thinking;
+	/** Whether the delegate closes itself after a normal completion; `auto_exit`, default true. */
 	autoExit: boolean;
-	/** Tools the delegate goes without, from `exclude-tools`; empty means all of them. */
-	excludeTools: string[];
-	/** The delegate's complete tool allowlist, from `tools`; empty means no `--tools` flag. */
-	tools: string[];
-	/** Absolute paths of extra extensions the delegate loads, from `extensions`; empty when absent. */
-	extensions: string[];
+	/** Current grant: true for the roster, or an explicit list of child identities. */
+	allowNested?: true | string[];
+	/** Presence of a permission map only; not a policy evaluation or privilege comparison. */
+	hasPermission?: boolean;
+	/**
+	 * The delegate's complete tool list, from a `tools` line of tool names:
+	 * undefined when the field is absent or holds only `-name` entries (the
+	 * parent's tools), empty when it is empty (no tools).
+	 */
+	tools?: string[];
+	/** The names or `*` patterns a `tools` line of only `-name` entries takes off the parent's tools; empty otherwise. */
+	toolsExcept: string[];
 	/** Models to try, in order, when `model` is usage-limited; from `fallback`, empty when absent. */
 	fallback: string[];
-	/** The body of `AGENT.md`: the delegate's system prompt. */
+	/** The fields a call cannot override, from `locked`. */
+	locked: Lockable[];
+	promptMode: PromptMode;
+	/** The body of the agent file: the delegate's instructions; may be empty. */
 	prompt: string;
+	/** The file the agent was read from. */
+	path: string;
 };
 
+/** An agent whose file is invalid: left out of the roster, and refused by name with `reason`. */
+export type Disabled = { name: string; path: string; reason: string };
+
 export type Roster = {
 	agents: Agent[];
-	/** One line per `AGENT.md` left out, naming its path and the reason. */
+	/** The agents whose files are invalid, by name; a call naming one is refused with its reason. */
+	disabled: Disabled[];
+	/** One line per agent file left out or field ignored, naming its path and the reason. */
 	warnings: string[];
 };
 
+/** The global agents folder, `<agent dir>/agents`. */
+export const globalAgentsDir = (agentDir: string): string => join(agentDir, "agents");
+
+/** A project's agents folder, `<cwd>/.pi/agents`. */
+export const projectAgentsDir = (cwd: string): string => join(cwd, ".pi", "agents");
+
 const field = (frontmatter: Record<string, unknown>, key: string): string | undefined => {
 	const value = frontmatter[key];
 	return typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
 };
 
-/** Parse one `AGENT.md`; undefined with a reason when it cannot be an agent. */
-function parseAgent(
-	name: string,
-	path: string,
-	text: string,
-	tools: readonly string[] | undefined,
-): { agent?: Agent; warning?: string; notes?: string[] } {
-	let frontmatter: Record<string, unknown>;
+/** One parsed file: the agent, or why it is invalid; neither for a file with `enabled: false`. */
+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 {
+	let frontmatter: unknown;
 	let body: string;
 	try {
-		({ frontmatter, body } = parseFrontmatter(text) as { frontmatter: Record<string, unknown>; body: string });
+		({ frontmatter, body } = parseFrontmatter(text) as { frontmatter: unknown; body: string });
 	} catch (err) {
-		return { warning: `${path} is not readable frontmatter (${(err as Error).message}); skipped` };
+		return { invalid: `${path} is not readable frontmatter (${(err as Error).message})`, notes: [] };
 	}
-	if (frontmatter === null || typeof frontmatter !== "object")
-		return { warning: `${path} has no frontmatter fields; skipped` };
-	const description = field(frontmatter, "description");
-	const model = field(frontmatter, "model");
-	const thinking = field(frontmatter, "thinking");
-	const missing = [
-		description === undefined ? "description" : undefined,
-		model === undefined ? "model" : undefined,
-		thinking === undefined ? "thinking" : undefined,
-	].filter((key): key is string => key !== undefined);
-	if (missing.length > 0) return { warning: `${path} has no ${missing.join(", ")}; skipped` };
-	if (!MODEL.test(model as string))
-		return { warning: `${path} has model ${JSON.stringify(model)}, not provider/id; skipped` };
-	if (!isThinking(thinking as string))
-		return {
-			warning: `${path} has thinking ${JSON.stringify(thinking)}, not one of ${THINKING_LEVELS.join(", ")}; skipped`,
-		};
-	if (body === "") return { warning: `${path} has no prompt body; skipped` };
-	const autoExit = flag(frontmatter["auto-exit"]);
+	if (frontmatter === null || typeof frontmatter !== "object" || Array.isArray(frontmatter))
+		return { invalid: `${path} has frontmatter that is not a set of fields`, notes: [] };
+	const fields = frontmatter as Record<string, unknown>;
+	const enabled = flag(fields.enabled);
+	if (enabled === null)
+		return { invalid: `${path} has enabled ${JSON.stringify(fields.enabled)}, not true or false`, notes: [] };
+	if (enabled === false) return { notes: [] };
+	const autoExit = flag(fields.auto_exit);
 	if (autoExit === null)
-		return { warning: `${path} has auto-exit ${JSON.stringify(frontmatter["auto-exit"])}, not true or false; skipped` };
-	const listed = toolList(frontmatter["exclude-tools"]);
-	if (listed === null)
-		return {
-			warning: `${path} has exclude-tools ${JSON.stringify(frontmatter["exclude-tools"])}, not a comma-separated list of tool names; skipped`,
-		};
-	const excludeTools = listed ?? [];
-	const unknownTool = tools === undefined ? undefined : excludeTools.find((tool) => !tools.includes(tool));
-	if (unknownTool !== undefined)
+		return { invalid: `${path} has auto_exit ${JSON.stringify(fields.auto_exit)}, not true or false`, notes: [] };
+	const nested = fields.allow_nested_delegation === false ? undefined : fields.allow_nested_delegation;
+	if (!validNested(nested))
 		return {
-			warning: `${path} has exclude-tools ${JSON.stringify(unknownTool)}, not a tool this session has; skipped`,
+			invalid: `${path} has allow_nested_delegation that is not true, false or a list of agent names`,
+			notes: [],
 		};
-	const launch = launchFields(path, frontmatter);
-	if ("warning" in launch) return launch;
-	// A bad fallback entry is dropped with a note; it never costs the agent.
+	const launch = toolsField(path, fields);
+	if ("invalid" in launch) return { ...launch, notes: [] };
+	const model = field(fields, "model");
+	const fallback = toolList(fields.fallback);
+	const pattern = patternProblem(path, model, fallback) ?? commaProblem(path, fields.fallback);
+	if (pattern !== undefined) return { invalid: pattern, notes: [] };
+	const shown = displayName(path, fields);
+	if ("invalid" in shown) return { ...shown, notes: [] };
+	// A field that cannot be used is dropped with a note; it never costs the agent.
 	const notes: string[] = [];
-	const listedFallback = toolList(frontmatter.fallback);
-	if (listedFallback === null)
-		notes.push(`${path} has fallback ${JSON.stringify(frontmatter.fallback)}, not a list of provider/id; ignored`);
-	const fallback = (listedFallback ?? []).filter((entry) => {
-		if (MODEL.test(entry)) return true;
-		notes.push(`${path} has fallback ${JSON.stringify(entry)}, not provider/id; dropped`);
-		return false;
-	});
+	const thinking = thinkingField(path, fields, notes);
+	warnDelegationTools(path, nested, launch.tools, notes);
+	if (fallback === null)
+		notes.push(`${path} has fallback ${JSON.stringify(fields.fallback)}, not a list of models; ignored`);
+	if (fields["exclude-tools"] !== undefined)
+		notes.push(`${path} has exclude-tools, which is no longer read; list the delegate's tools in tools instead`);
 	return {
 		notes,
 		agent: {
 			name,
-			description: description as string,
-			model: model as string,
-			thinking: thinking as Thinking,
+			...shown,
+			description: field(fields, "description") ?? name,
+			...(model === undefined ? {} : { model }),
+			...(thinking === undefined ? {} : { thinking }),
 			autoExit: autoExit ?? true,
-			excludeTools,
+			...(nested === undefined ? {} : { allowNested: nested === true ? true : [...new Set(nested as string[])] }),
+			hasPermission:
+				fields.permission !== null && typeof fields.permission === "object" && !Array.isArray(fields.permission),
 			...launch,
-			fallback,
-			prompt: body,
+			fallback: fallback ?? [],
+			locked: lockedFields(path, fields, { model, thinking }, notes),
+			promptMode: promptMode(path, fields, notes),
+			prompt: body.trim(),
+			path,
 		},
 	};
 }
 
-/** The `tools` and `extensions` fields, or the warning that leaves the agent out. */
-function launchFields(
+function warnDelegationTools(path: string, nested: unknown, tools: string[] | undefined, notes: string[]): void {
+	if (nested === true || (Array.isArray(nested) && nested.length > 0)) return;
+	if (
+		tools?.some((name) =>
+			["delegate", "delegation_status", "delegation_close", "delegation_resume"].some((tool) =>
+				toolMatches(name, tool),
+			),
+		)
+	)
+		notes.push(
+			`${path} lists delegation tools without allow_nested_delegation; listing tools alone does not grant nesting`,
+		);
+}
+
+function validNested(value: unknown): boolean {
+	return (
+		value === undefined ||
+		value === true ||
+		(Array.isArray(value) && value.every((entry) => typeof entry === "string" && NAME.test(entry)))
+	);
+}
+
+/**
+ * Why a `model` or `fallback` entry makes the file invalid: a `*` pattern.
+ * Each entry names one model (an exact `provider/id` or an alias Pi resolves
+ * to one model), at launch through Pi's `--model` and in the delegate's own
+ * switch after a usage limit.
+ */
+function patternProblem(
+	path: string,
+	model: string | undefined,
+	fallback: string[] | null | undefined,
+): string | undefined {
+	if (model?.includes("*"))
+		return `${path} has model ${JSON.stringify(model)}: * patterns are not accepted; name one model, as provider/id or an alias`;
+	const entry = (fallback ?? []).find((name) => name.includes("*"));
+	if (entry !== undefined)
+		return `${path} has fallback ${JSON.stringify(entry)}: * patterns are not accepted; name one model per entry, as provider/id or an alias`;
+	return undefined;
+}
+
+/** Why a `fallback` list entry holding a comma makes the file invalid: each entry names one model. */
+function commaProblem(path: string, fallback: unknown): string | undefined {
+	const entry = commaEntry(fallback);
+	return entry === undefined
+		? undefined
+		: `${path} has fallback entry ${JSON.stringify(entry)}, which holds a comma; name one model per entry, or write fallback as one comma-separated line`;
+}
+
+/** The `thinking` field; an unknown level is dropped with a note, so the parent's level applies. */
+function thinkingField(path: string, fields: Record<string, unknown>, notes: string[]): Thinking | undefined {
+	if (fields.thinking === undefined || fields.thinking === null) return undefined;
+	const value = typeof fields.thinking === "string" ? fields.thinking.trim() : undefined;
+	if (value !== undefined && isThinking(value)) return value;
+	notes.push(
+		`${path} has thinking ${JSON.stringify(fields.thinking)}, not one of ${THINKING_LEVELS.join(", ")}; the parent's level applies`,
+	);
+	return undefined;
+}
+
+/** The `display_name` field, as a spread, or why the file is invalid: anything but `[A-Za-z0-9_-]+`, empty included. */
+function displayName(path: string, fields: Record<string, unknown>): { displayName?: string } | { invalid: string } {
+	if (!Object.hasOwn(fields, "display_name")) return {};
+	const value = fields.display_name;
+	if (typeof value === "string" && DISPLAY_NAME.test(value)) return { displayName: value };
+	return {
+		invalid: `${path} has display_name ${JSON.stringify(value)}, which may hold only ASCII letters, digits, - and _`,
+	};
+}
+
+/** The `prompt_mode` field; an unknown mode is ignored with a note, so the default applies. */
+function promptMode(path: string, fields: Record<string, unknown>, notes: string[]): PromptMode {
+	const value = fields.prompt_mode;
+	if (value === undefined || value === null || value === "append") return "append";
+	if (value === "replace") return "replace";
+	notes.push(`${path} has prompt_mode ${JSON.stringify(value)}, not append or replace; append applies`);
+	return "append";
+}
+
+/** The `locked` field: `true` locks the lockable fields the file sets; a list names them. */
+function lockedFields(
+	path: string,
+	fields: Record<string, unknown>,
+	set: { model?: string; thinking?: string },
+	notes: string[],
+): Lockable[] {
+	const value = fields.locked;
+	if (value === undefined || value === null || value === false) return [];
+	if (value === true) return LOCKABLE.filter((key) => set[key] !== undefined);
+	const names = toolList(value);
+	if (names === null || names === undefined) {
+		notes.push(`${path} has locked ${JSON.stringify(value)}, not true or a list of model and thinking; ignored`);
+		return [];
+	}
+	const locked: Lockable[] = [];
+	for (const entry of names) {
+		if ((LOCKABLE as readonly string[]).includes(entry)) {
+			if (!locked.includes(entry as Lockable)) locked.push(entry as Lockable);
+		} else notes.push(`${path} has locked ${JSON.stringify(entry)}, not model or thinking; dropped`);
+	}
+	return locked;
+}
+
+/**
+ * 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.
+ */
+function toolsField(
 	path: string,
 	frontmatter: Record<string, unknown>,
-): { tools: string[]; extensions: string[] } | { warning: string } {
-	const tools = toolList(frontmatter.tools);
+): { 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);
 	if (tools === null)
 		return {
-			warning: `${path} has tools ${JSON.stringify(frontmatter.tools)}, not a comma-separated list of tool names; skipped`,
+			invalid: `${path} has tools ${JSON.stringify(frontmatter.tools)}, not a comma-separated list of tool names`,
 		};
-	const paths = toolList(frontmatter.extensions);
-	if (paths === null)
+	if (tools === undefined) return { toolsExcept: [] };
+	const comma = commaEntry(frontmatter.tools);
+	if (comma !== undefined)
 		return {
-			warning: `${path} has extensions ${JSON.stringify(frontmatter.extensions)}, not a comma-separated list of paths; skipped`,
+			invalid: `${path} has tools entry ${JSON.stringify(comma)}, which holds a comma; give one tool per entry, or write tools as one comma-separated line`,
 		};
-	const extensions = (paths ?? []).map((entry) => resolveExtension(entry, dirname(path)));
-	const absent = extensions.find((entry) => !existsSync(entry));
-	if (absent !== undefined) return { warning: `${path} has extension ${absent}, which does not exist; skipped` };
-	return { tools: tools ?? [], extensions };
-}
-
-/** An extension path as an absolute one: `~` is the home directory, a relative path is against the AGENT.md's directory. */
-function resolveExtension(entry: string, dir: string): string {
-	if (entry === "~") return homedir();
-	if (entry.startsWith("~/")) return join(homedir(), entry.slice(2));
-	return isAbsolute(entry) ? entry : resolve(dir, entry);
+	const plus = tools.find((name) => name.startsWith("+"));
+	if (plus !== undefined)
+		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 minus = tools.filter((name) => name.startsWith("-"));
+	if (minus.length === 0) return { tools, toolsExcept: [] };
+	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`,
+		};
+	const bare = minus.find((name) => name.slice(1).trim() === "");
+	if (bare !== undefined) return { invalid: `${path} has tools entry ${JSON.stringify(bare)}, which names no tool` };
+	return { toolsExcept: minus.map((name) => name.slice(1).trim()) };
 }
 
 /** A list of names (tools or models), comma-separated or a YAML list of names; undefined when absent, null when it is neither. */
@@ -169,6 +317,16 @@ function toolList(value: unknown): string[] | undefined | null {
 	return names.map((name) => name.trim()).filter((name) => name !== "");
 }
 
+/**
+ * The first entry of a YAML list `value` that holds a comma, such as
+ * `["read,-bash"]`: one entry must name one thing. Undefined for a list
+ * without one, and for a comma-separated line, which `toolList` splits.
+ */
+function commaEntry(value: unknown): string | undefined {
+	if (!Array.isArray(value)) return undefined;
+	return value.find((entry): entry is string => typeof entry === "string" && entry.includes(","));
+}
+
 /** A true/false frontmatter value; undefined when absent, null when it is neither. */
 function flag(value: unknown): boolean | undefined | null {
 	if (value === undefined || value === null) return undefined;
@@ -178,39 +336,152 @@ function flag(value: unknown): boolean | undefined | null {
 	return null;
 }
 
-/**
- * Read every agent under `<agentDir>/squire/agents/`, in name order. A directory
- * with no `AGENT.md` is not an agent and is passed over quietly; an
- * `AGENT.md` that cannot be used is warned about and left out. `tools` are
- * the session's tool names, which `exclude-tools` is checked against;
- * undefined skips that check, as before the session's tools are known.
- */
-export function readRoster(agentDir: string, tools?: readonly string[]): Roster {
-	const dir = join(agentDir, "squire", "agents");
-	let names: string[];
+/** The `<name>.md` files directly in `dir`, by name; empty when there is no such folder. */
+function agentFiles(dir: string): Map<string, string> {
+	const files = new Map<string, string>();
+	let entries: string[];
 	try {
-		names = readdirSync(dir).sort();
+		entries = readdirSync(dir);
 	} catch {
-		return { agents: [], warnings: [] }; // no agents directory yet
+		return files; // no agents folder
 	}
-	const agents: Agent[] = [];
-	const warnings: string[] = [];
-	for (const name of names) {
-		const path = join(dir, name, "AGENT.md");
-		let text: string;
+	for (const entry of entries.sort()) {
+		if (!entry.endsWith(".md")) continue;
+		const path = join(dir, entry);
 		try {
-			text = readFileSync(path, "utf8");
+			if (!statSync(path).isFile()) continue;
 		} catch {
 			continue;
 		}
+		files.set(entry.slice(0, -".md".length), path);
+	}
+	return files;
+}
+
+/**
+ * Read every agent, in name order: the global folder, then `projectDir` when
+ * given, whose files replace global ones of the same name. The caller passes
+ * `projectDir` only for a trusted project. A file that cannot be used is
+ * disabled: left out, warned about and kept in `disabled` with why; a file
+ * with `enabled: false` is left out quietly.
+ */
+export function readRoster(agentDir: string, projectDir?: string): Roster {
+	const files = agentFiles(globalAgentsDir(agentDir));
+	if (projectDir !== undefined) for (const [name, path] of agentFiles(projectDir)) files.set(name, path);
+	const agents: Agent[] = [];
+	const disabled: Disabled[] = [];
+	const warnings: string[] = [];
+	const retired = join(agentDir, "squire", "agents");
+	if (existsSync(retired))
+		warnings.push(
+			`${retired} is no longer read; move each <name>/AGENT.md there to ${join(globalAgentsDir(agentDir), "<name>.md")}`,
+		);
+	const disable = (name: string, path: string, reason: string): void => {
+		disabled.push({ name, path, reason });
+		warnings.push(`${reason}; skipped`);
+	};
+	for (const name of [...files.keys()].sort()) {
+		const path = files.get(name) as string;
 		if (!NAME.test(name)) {
-			warnings.push(`${path} is not under a usable agent name; skipped`);
+			disable(name, path, `${path} is not named as a usable agent (letters, digits, _ or -)`);
+			continue;
+		}
+		let text: string;
+		try {
+			text = readFileSync(path, "utf8");
+		} catch (err) {
+			disable(name, path, `${path} could not be read (${(err as Error).message})`);
 			continue;
 		}
-		const { agent, warning, notes } = parseAgent(name, path, text, tools);
-		warnings.push(...(notes ?? []));
+		const { agent, invalid, notes } = parseAgent(name, path, text);
+		warnings.push(...notes);
 		if (agent !== undefined) agents.push(agent);
-		else if (warning !== undefined) warnings.push(warning);
+		else if (invalid !== undefined) disable(name, path, invalid);
+	}
+	for (const agent of agents) {
+		const targets = agent.allowNested === true ? agents.map((item) => item.name) : (agent.allowNested ?? []);
+		for (const name of targets) {
+			const child = agents.find((item) => item.name === name);
+			if (!child)
+				warnings.push(
+					`${agent.path} allows unknown or unavailable nested agent ${JSON.stringify(name)}; it cannot launch until present in the current roster`,
+				);
+			else if (agent.hasPermission && !child.hasPermission)
+				warnings.push(
+					`${agent.path} grants nested agent ${JSON.stringify(name)} (${child.path}) without a permission block; this is a delegation grant, not proof of equal or lesser permission authority`,
+				);
+		}
+	}
+	return { agents, disabled, warnings };
+}
+
+/** The refusal for a call that names a disabled agent; undefined when `name` is not one. */
+export function disabledProblem(roster: Roster, name: string): string | undefined {
+	const found = roster.disabled.find((item) => item.name === name);
+	return found === undefined
+		? undefined
+		: `agent ${JSON.stringify(name)} is disabled because its file is invalid: ${found.reason}`;
+}
+
+/**
+ * A call's `model` and `thinking` with every field `agent` locks taken out,
+ * so the call runs as if it had passed none of them, and the notice for those
+ * it passed with a value other than `locked`, the value the lock keeps (the
+ * file's, or the parent's when the file sets none). A locked field passed with
+ * that value is no override: it is dropped quietly.
+ */
+export function withoutLocked<T extends { model?: string; thinking?: string }>(
+	agent: Agent,
+	request: T,
+	locked: { model?: string; thinking?: string },
+): { request: T; notice?: string } {
+	const passed = agent.locked.filter((key) => request[key] !== undefined);
+	if (passed.length === 0) return { request };
+	const kept = { ...request };
+	for (const key of passed) delete kept[key];
+	const refused = passed.filter((key) => request[key] !== locked[key]);
+	if (refused.length === 0) return { request: kept };
+	const given = refused.map((key) => `${key} ${request[key]}`).join(" and ");
+	return {
+		request: kept,
+		notice: `Agent ${agent.name} locks ${refused.join(" and ")}, so the ${given} given ${refused.length > 1 ? "were" : "was"} not used.`,
+	};
+}
+
+/**
+ * The `delegateTools` setting in `<agent dir>/squire/settings.json`: tool
+ * names or `*` patterns added to every delegate's tools, whether they come
+ * from the agent's `tools` or the parent. Empty when unset or when the file
+ * cannot be read or parsed (the worktree settings report that when a launch
+ * needs them); a value that is not a list of names, or an entry holding a
+ * comma or starting with `+` or `-`, refuses the launch with the file named.
+ */
+export function delegateTools(agentDir: string): string[] {
+	const file = join(agentDir, "squire", "settings.json");
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(readFileSync(file, "utf8"));
+	} catch {
+		return [];
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return [];
+	const value = (parsed as Record<string, unknown>).delegateTools;
+	if (value === undefined) return [];
+	if (!Array.isArray(value) || !value.every((entry) => typeof entry === "string" && entry.trim() !== "")) {
+		throw new Error(
+			`invalid delegate tools settings ${file}: delegateTools must be a list of tool names or patterns, not ${JSON.stringify(value)}`,
+		);
 	}
-	return { agents, warnings };
+	const names = value.map((entry: string) => entry.trim());
+	const comma = names.find((name) => name.includes(","));
+	if (comma !== undefined)
+		throw new Error(
+			`invalid delegate tools settings ${file}: delegateTools entry ${JSON.stringify(comma)} holds a comma; give one tool name or pattern per entry`,
+		);
+	const modifier = names.find((name) => name.startsWith("+") || name.startsWith("-"));
+	if (modifier !== undefined)
+		throw new Error(
+			`invalid delegate tools settings ${file}: delegateTools entries are tool names; ${JSON.stringify(modifier)} starts with ${modifier[0]}, which is not accepted there`,
+		);
+	return names;
 }