dsh-pstack 0.1.0 → 0.2.0-beta.3

package/dist/subagent.mjs

@@ -1,436 +1,1104 @@
-import { n as SKILLS_ROOT, t as AGENTS_ROOT } from "./paths-Bbai4CaT.mjs";
-import { readFile } from "node:fs/promises";
-import { ReasoningEffortId } from "@deepseek-ai/dsh-llm";
-import { defineTool } from "@deepseek-ai/dsh-tools";
+import { a as POTETO_MODE_SKILL_PATH } from "./paths-BT77khwm.mjs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
-//#region src/roles.ts
-const INHERIT = /* @__PURE__ */ new Set([
-	"inherit-parent",
-	"auto",
-	"parent"
-]);
+// src/internal/effort.ts
+/** Model-facing name of the child's own control. */
+const SET_EFFORT_TOOL = "set_reasoning_effort";
 /**
-* Reasoning efforts DSH understands, widest first. A token outside this set is
-* reported rather than dropped: a route that silently loses `xhigh` looks
-* configured and is not.
+* Resolve the route a child's effort will actually apply to: an explicit route wins,
+* then the session's live request header, then the creation-time options.
 */
-const REASONING_EFFORTS = [
-	"max",
-	"xhigh",
-	"high",
-	"medium",
-	"low",
-	"off"
+function resolveEffortTarget(agent, route) {
+	const explicit = route?.kind === "route" ? route : void 0;
+	const header = agent?.session.requestHeader()?.config;
+	const provider = explicit?.provider ?? header?.provider ?? agent?.options.provider;
+	const model = explicit?.model ?? header?.model ?? agent?.options.model;
+	return provider !== void 0 && model !== void 0 ? {
+		provider,
+		model
+	} : void 0;
+}
+async function advertisedEfforts(llm, target, signal) {
+	return (await llm.resolveModelInfo(target.provider, target.model, signal)).reasoning?.efforts.map((entry) => entry.id) ?? [];
+}
+/** Validate one effort against the route a child will actually request. */
+async function validateEffortFor(llm, route, effort, parent, signal) {
+	const target = resolveEffortTarget(parent, route);
+	if (target === void 0) throw new Error("cannot resolve the child provider/model route for reasoningEffort. Pass `role` with an exact route, or run the delegation from a session that has already made a request.");
+	let efforts;
+	try {
+		efforts = await advertisedEfforts(llm, target, signal);
+	} catch (error) {
+		throw new Error(`route ${target.provider}/${target.model} could not be resolved for reasoningEffort: ${describeError$2(error)}`, { cause: error });
+	}
+	if (efforts.length === 0) throw new Error(`${target.provider}/${target.model} advertises no reasoning efforts, so it cannot take reasoningEffort "${effort}". Omit the argument and let the adapter use its own default.`);
+	if (!efforts.includes(effort)) throw new Error(`${target.provider}/${target.model} does not support reasoning effort "${effort}". It supports: ${efforts.join(", ")}.`);
+}
+/**
+* Install the effort control on one live child.
+*
+* Registration is child-scoped, so the tool disposes with the child. A successful
+* call records the choice through `agent.model.select()`, which DSH applies when
+* it prepares the next step. `agent/request` is deliberately not used: DSH
+* deprecated it for model and effort changes and rejects a request that disagrees
+* with the selection fixed during step preparation.
+*/
+function installEffortControl(child, llm) {
+	return child.ctx.tools.register(defineSetEffortTool(child, llm));
+}
+function defineSetEffortTool(child, llm) {
+	return {
+		name: SET_EFFORT_TOOL,
+		description: [
+			"Change your reasoning effort for future model requests.",
+			"Use it when the task turns out harder or more routine than the role line assumed: raise it for subtle design, concurrency, or algorithm work, lower it once the remaining work is mechanical.",
+			"The change applies from your next step; a request already in flight is unaffected, and it lasts for the rest of this child's life."
+		].join(" "),
+		parameters: {
+			type: "object",
+			additionalProperties: false,
+			properties: { effort: {
+				type: "string",
+				description: "The reasoning effort to use from your next step onward. Use one of the values this model advertises; the call rejects an unknown one and lists the real values."
+			} },
+			required: ["effort"]
+		},
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: typeof value === "string" ? value : JSON.stringify(value)
+			}]
+		},
+		isConcurrencySafe: () => false,
+		async execute(rawArgs, exec) {
+			const args = rawArgs;
+			const value = typeof args.effort === "string" ? args.effort.trim() : "";
+			if (value === "") throw new Error("set_reasoning_effort needs a non-empty `effort`. Pass the exact token this model advertises; an empty value would silently re-enable the adapter default.");
+			const agent = exec.agent ?? child;
+			const target = resolveEffortTarget(agent);
+			if (target === void 0) throw new Error("this child has no resolved provider/model route, so reasoning effort cannot be validated against the live adapter metadata");
+			let efforts;
+			try {
+				efforts = await advertisedEfforts(llm, target, exec.signal);
+			} catch (error) {
+				throw new Error(`${target.provider}/${target.model} could not be resolved for reasoning effort: ${describeError$2(error)}`, { cause: error });
+			}
+			if (efforts.length === 0) throw new Error(`${target.provider}/${target.model} advertises no reasoning efforts, so this child has none to change. Your current effort stays as it is.`);
+			if (!efforts.includes(value)) throw new Error(`${target.provider}/${target.model} does not support reasoning effort "${value}", so nothing changed. It supports: ${efforts.join(", ")}.`);
+			agent.model.select({
+				provider: target.provider,
+				model: target.model,
+				reasoningEffort: value
+			});
+			return `reasoning effort set to "${value}". It applies from your next step; the request already in flight is unaffected.`;
+		}
+	};
+}
+/** The `agentOptions` one (route, effort override) pair contributes. */
+function agentOptionsFor(route, effortOverride) {
+	const effort = effortOverride ?? (route.kind === "route" ? route.effort : void 0);
+	if (route.kind === "inherit") return effort === void 0 ? void 0 : { reasoningEffort: effort };
+	return {
+		provider: route.provider,
+		model: route.model,
+		...effort === void 0 ? {} : { reasoningEffort: effort }
+	};
+}
+/** The effort a plan entry will actually run at, override included. */
+function effectiveEffort(route, effortOverride) {
+	return effortOverride ?? (route.kind === "route" ? route.effort : void 0);
+}
+function describeError$2(error) {
+	if (error instanceof Error) {
+		const code = error.code;
+		return typeof code === "string" ? `${error.message} (${code})` : error.message;
+	}
+	return String(error);
+}
+// src/internal/role-manifest.ts
+/**
+* File name the role configuration lives under inside `$DSH_HOME`.
+*
+* It keeps the upstream name `pstack-models.mdc`, so a reader moving from the Cursor docs
+* recognizes it, but stores it directly under `$DSH_HOME`; DSH does not load `.mdc` files
+* on its own, and `pstack_subagent` is the only reader.
+*/
+const PSTACK_MODELS_FILENAME = "pstack-models.mdc";
+/** Values that resolve to "send no `agentOptions` and inherit the parent route". */
+const INHERIT_PARENT_ALIASES = ["inherit-parent", "auto"];
+/** The 17 roles, in manifest order. */
+const ROLE_MANIFEST = [
+	{
+		key: "feature, refactoring",
+		shape: "single",
+		autoPanel: false
+	},
+	{
+		key: "bug-fix",
+		shape: "single",
+		autoPanel: false
+	},
+	{
+		key: "perf-issue",
+		shape: "single",
+		autoPanel: false
+	},
+	{
+		key: "hillclimb",
+		shape: "single",
+		autoPanel: false
+	},
+	{
+		key: "judgment and prose",
+		shape: "single",
+		autoPanel: false
+	},
+	{
+		key: "hardest tasks",
+		shape: "single",
+		autoPanel: false
+	},
+	{
+		key: "how explorer",
+		shape: "single",
+		autoPanel: false
+	},
+	{
+		key: "how explainer",
+		shape: "single",
+		autoPanel: false
+	},
+	{
+		key: "why investigators",
+		shape: "single",
+		autoPanel: false
+	},
+	{
+		key: "why synthesizer",
+		shape: "single",
+		autoPanel: false
+	},
+	{
+		key: "reflect tooling",
+		shape: "single",
+		autoPanel: false
+	},
+	{
+		key: "reflect judgment, divergent, synthesizer",
+		shape: "single",
+		autoPanel: false
+	},
+	{
+		key: "arena runners",
+		shape: "list",
+		autoPanel: true
+	},
+	{
+		key: "arena cross-judge pool",
+		shape: "list",
+		autoPanel: false
+	},
+	{
+		key: "swarm workers",
+		shape: "list",
+		autoPanel: false
+	},
+	{
+		key: "architect runners",
+		shape: "list",
+		autoPanel: true
+	},
+	{
+		key: "interrogate reviewers",
+		shape: "list",
+		autoPanel: true
+	}
 ];
-const EFFORTS = new Set(REASONING_EFFORTS);
+/** Exact manifest lookup. Callers normalize the key first. */
+function findRoleSpec(key) {
+	return ROLE_MANIFEST.find((role) => role.key === key);
+}
+// src/internal/role-config.ts
 /**
-* Register the role names on one line.
+* The pstack role configuration: `$DSH_HOME/pstack-models.mdc`.
+*
+* `pstack_subagent` reads this file again on every delegation, so a change reaches the
+* next child and never a child that already started.
 *
-* The whole left side is always stored as one key, so
-* `reflect judgment, divergent, synthesizer` stays addressable as written.
-* When the comma list is a genuine group (`feature, refactoring`), each part is
-* stored too, so a caller can name just one of them. Both spellings therefore
-* work, and neither can shadow the other: the full key is a different string.
+* Three states stay apart because each needs a different fix: the file is missing (no
+* policy, so every role inherits the parent route), unreadable (a broken install, never
+* treated as "no configuration"), or loaded with per-line issues reported by line.
 */
-function splitRoles(left) {
-	const whole = left.trim().toLowerCase().replace(/\s+/g, " ");
-	if (!whole) return [];
-	const parts = left.split(",").map((part) => part.trim().toLowerCase()).filter(Boolean);
-	return parts.length > 1 ? [whole, ...parts] : [whole];
-}
-function parseModelConfigWithIssues(source) {
-	const table = /* @__PURE__ */ new Map();
+/** Absolute path of the role file for one DSH home. */
+function modelsFilePath(dshHome) {
+	return join(dshHome, PSTACK_MODELS_FILENAME);
+}
+/** Resolve `$DSH_HOME` the way the Host does: the environment when set, else `~/.dsh`. */
+function resolveDshHome(env = process.env, home = homedir()) {
+	const configured = env["DSH_HOME"];
+	const path = configured !== void 0 && configured.trim() !== "" ? configured : join(home, ".dsh");
+	const expanded = path === "~" ? home : path.startsWith("~/") || path.startsWith("~\\") ? join(home, path.slice(2)) : path;
+	return resolve(expanded);
+}
+/** Read the role file. Never throws for a missing or unreadable file. */
+function readRoleConfiguration(path) {
+	let text;
+	try {
+		text = readFileSync(path, "utf8");
+	} catch (error) {
+		if (isMissingFile(error)) return {
+			status: "missing",
+			path
+		};
+		return {
+			status: "unreadable",
+			path,
+			reason: describeError$1(error)
+		};
+	}
+	return parseRoleConfiguration(text, path);
+}
+/** Parse role-file text. Pure: no file system access. */
+function parseRoleConfiguration(text, path) {
 	const issues = [];
-	const lines = source.replace(/\r\n/g, "\n").split("\n");
-	for (const [index, rawLine] of lines.entries()) {
-		const line = rawLine.trim();
-		if (!line || line.startsWith("#") || line.startsWith("//")) continue;
-		const lineNumber = index + 1;
-		const separator = line.indexOf(":");
+	const roles = /* @__PURE__ */ new Map();
+	let budget;
+	stripFrontmatter(text).split("\n").forEach((rawLine, index) => {
+		const line = index + 1;
+		const trimmed = rawLine.trim();
+		if (trimmed === "") return;
+		if (trimmed.startsWith("#")) {
+			const match = /^#\s*budget:\s*(.+)$/i.exec(trimmed);
+			if (match !== null) budget = match[1].trim();
+			return;
+		}
+		const separator = trimmed.indexOf(":");
 		if (separator === -1) {
 			issues.push({
-				line: lineNumber,
-				message: `expected "role: value", got ${JSON.stringify(line)}`
+				line,
+				message: `expected \`<role>: <value>\`, found ${JSON.stringify(trimmed)}`
 			});
-			continue;
+			return;
 		}
-		const roles = splitRoles(line.slice(0, separator));
-		if (roles.length === 0) {
+		const rawKey = trimmed.slice(0, separator).trim();
+		const rawValue = trimmed.slice(separator + 1).trim();
+		const key = normalizeRoleName(rawKey);
+		if (key === "") {
 			issues.push({
-				line: lineNumber,
-				message: "no role name before the colon"
+				line,
+				message: "the role key is empty"
 			});
-			continue;
+			return;
 		}
-		const values = [];
-		for (const entry of line.slice(separator + 1).split(",")) {
-			const parsed = parseValue(entry.trim(), lineNumber, issues);
-			if (parsed !== void 0) values.push(parsed);
-		}
-		if (values.length === 0) {
+		const spec = findRoleSpec(key);
+		if (spec === void 0) {
 			issues.push({
-				line: lineNumber,
-				message: `no usable value for ${roles.join(", ")}`
+				line,
+				message: unknownRoleMessage(rawKey, key)
 			});
-			continue;
+			return;
 		}
-		for (const role of roles) table.set(role, values);
-	}
-	return {
-		table,
-		issues
-	};
-}
-function parseValue(value, line = 0, issues = []) {
-	if (!value) return void 0;
-	if (INHERIT.has(value.toLowerCase())) return "inherit-parent";
-	const [route, ...rest] = value.split(/\s+/).filter(Boolean);
-	if (!route) return void 0;
-	const slash = route.indexOf("/");
-	if (slash <= 0 || slash === route.length - 1) {
-		issues.push({
+		const parsed = parseRouteValue(rawValue);
+		const entryIssues = [...parsed.issues];
+		if (spec.shape === "single" && parsed.routes.length > 1) entryIssues.push("a single-route role cannot hold a comma-separated list");
+		for (const issue of entryIssues) issues.push({
 			line,
-			message: `"${route}" is not <provider>/<model>, so this role inherits the parent route`
+			message: `${rawKey}: ${issue}`
 		});
-		return "inherit-parent";
-	}
-	let reasoningEffort;
-	for (const token of rest) {
-		if (EFFORTS.has(token.toLowerCase())) {
-			reasoningEffort = token.toLowerCase();
-			continue;
-		}
-		issues.push({
+		if (parsed.routes.length === 0) return;
+		const previous = roles.get(spec.key);
+		if (previous !== void 0) issues.push({
 			line,
-			message: `unknown effort "${token}"; expected one of ${REASONING_EFFORTS.join(", ")}`
+			message: `role "${spec.key}" is already configured on line ${previous.line}; line ${line} wins`
 		});
-	}
+		roles.set(spec.key, {
+			line,
+			rawKey,
+			key: spec.key,
+			spec,
+			routes: parsed.routes,
+			issues: entryIssues
+		});
+	});
+	return budget === void 0 ? {
+		status: "loaded",
+		path,
+		roles,
+		issues
+	} : {
+		status: "loaded",
+		path,
+		budget,
+		roles,
+		issues
+	};
+}
+/** Parse a role value: one route, or a comma-separated list of routes. */
+function parseRouteValue(raw) {
+	const routes = [];
+	const issues = [];
+	const segments = raw.split(",");
+	segments.forEach((segment, index) => {
+		const trimmed = segment.trim();
+		if (trimmed === "") {
+			if (index !== segments.length - 1) issues.push(`entry ${index + 1} of the list is empty`);
+			return;
+		}
+		const parsed = parseRoute(trimmed);
+		if (parsed.route === void 0) {
+			issues.push(parsed.issue);
+			return;
+		}
+		routes.push(parsed.route);
+	});
+	if (routes.length === 0 && issues.length === 0) issues.push("the value is empty; use `inherit-parent`, `auto`, or `<provider>/<model> [effort]`");
 	return {
-		provider: route.slice(0, slash),
-		model: route.slice(slash + 1),
-		...reasoningEffort ? { reasoningEffort } : {}
+		routes,
+		issues
 	};
 }
+/** Parse one entry of a role value. */
+function parseRoute(raw) {
+	const value = raw.trim();
+	if (value === "") return { issue: "the value is empty" };
+	if (INHERIT_PARENT_ALIASES.includes(value.toLowerCase())) return { route: { kind: "inherit" } };
+	const match = /^([^\s/,[]+)\/([^\s/,[\]]+(?:\/[^\s/,[\]]+)*)(?:\s+\[([^[\]]*)\])?$/.exec(value);
+	if (match === null) return { issue: `${JSON.stringify(value)} is not a route; use \`inherit-parent\`, \`auto\`, or \`<provider>/<model> [effort]\`` };
+	const provider = match[1];
+	const model = match[2];
+	const effort = match[3];
+	if (effort === void 0) return { route: {
+		kind: "route",
+		provider,
+		model
+	} };
+	const trimmedEffort = effort.trim();
+	if (trimmedEffort === "") return { issue: `${JSON.stringify(value)} has empty brackets; write \`<provider>/<model> [effort]\` or drop the brackets` };
+	if (/\s/.test(trimmedEffort)) return { issue: `${JSON.stringify(value)} has a multi-word effort; an effort is one adapter-owned token` };
+	return { route: {
+		kind: "route",
+		provider,
+		model,
+		effort: trimmedEffort
+	} };
+}
+/** Raised when a role's configured list cannot be selected from. */
+var RouteSelectionError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "RouteSelectionError";
+	}
+};
 /**
-* Look a role up by name.
+* Expand one role into the routes this call starts.
 *
-* The parser stores both the whole left side of a line and, when the comma list
-* is a genuine group, each part. So a direct map hit is the only match worth
-* making. Matching is exact on purpose: a near miss such as `how` against
-* `how explorer` must not resolve, because picking a route the user did not name
-* changes both cost and model without saying so. `findNearMisses` reports those
-* for a human instead.
+* Automatic panels start one child per entry. Another list role selects one entry, the
+* first by default; `roleIndex` chooses which. A single role holds exactly one route and
+* rejects `roleIndex`.
 */
-function lookupRole(table, role) {
-	if (!role) return void 0;
-	const key = role.trim().toLowerCase().replace(/\s+/g, " ");
-	if (!key) return void 0;
-	const values = table.get(key);
-	if (!values) return void 0;
+function selectRoleRoutes(spec, entry, roleIndex) {
+	if (spec.shape === "single" && roleIndex !== void 0) throw new RouteSelectionError(`role "${spec.key}" holds a single route, so \`roleIndex\` does not apply; drop \`roleIndex\` or use a list-valued role (${listRoleKeys().join(", ")})`);
+	if (spec.autoPanel && roleIndex !== void 0) throw new RouteSelectionError(`role "${spec.key}" is an automatic panel: it starts one child per entry, so \`roleIndex\` does not apply`);
+	if (entry === void 0) return {
+		role: spec,
+		mode: spec.autoPanel ? "panel" : "single",
+		configured: false,
+		routes: [{ kind: "inherit" }],
+		total: 1
+	};
+	if (entry.issues.length > 0) throw new RouteSelectionError(`role "${spec.key}" has invalid configuration on line ${entry.line}: ${entry.issues.join("; ")}. Fix the role file before delegating.`);
+	if (spec.autoPanel) return {
+		role: spec,
+		mode: "panel",
+		configured: true,
+		routes: entry.routes,
+		total: entry.routes.length
+	};
+	if (spec.shape === "list") {
+		const index = roleIndex ?? 0;
+		if (index >= entry.routes.length) throw new RouteSelectionError(`role "${spec.key}" has ${entry.routes.length} entr${entry.routes.length === 1 ? "y" : "ies"}, so \`roleIndex\` ${index} is out of range; valid indexes are ${entry.routes.map((_route, position) => position).join(", ")}`);
+		return {
+			role: spec,
+			mode: "selected",
+			configured: true,
+			routes: [entry.routes[index]],
+			total: entry.routes.length,
+			roleIndex: index
+		};
+	}
 	return {
-		key,
-		values,
-		fromList: key.includes(",")
+		role: spec,
+		mode: "single",
+		configured: true,
+		routes: [entry.routes[0]],
+		total: entry.routes.length
 	};
 }
-/**
-* Configured role names a caller could have meant. Used to explain a miss, not
-* to resolve one: `how` is a near miss for `how explorer`, and quietly running
-* on the explorer route would look configured while being wrong.
-*/
-function findNearMisses(table, role) {
-	const key = role.trim().toLowerCase().replace(/\s+/g, " ");
-	if (!key) return [];
-	const hits = [];
-	for (const candidate of table.keys()) {
-		if (candidate === key) continue;
-		if (candidate.includes(key) || key.includes(candidate)) {
-			hits.push(candidate);
-			continue;
-		}
-		for (const part of candidate.split(",").map((item) => item.trim())) {
-			if (part === key) continue;
-			if (part.includes(key) || key.includes(part)) {
-				hits.push(candidate);
-				break;
-			}
-		}
-	}
-	return [...new Set(hits)];
+/** Keys of the list-valued roles, including the automatic panels. */
+function listRoleKeys() {
+	return ROLE_MANIFEST.filter((role) => role.shape === "list").map((role) => role.key);
 }
-/**
-* Resolve one role to a route.
-*
-* `index` selects a panel entry and wraps, so a caller that spawns more
-* children than the list has entries still gets a deterministic route. A
-* missing role or an `inherit-parent` entry both return `undefined`, which
-* tells the caller to omit `agentOptions` and inherit.
-*/
-function resolveRole(table, role, index = 0) {
-	const values = lookupRole(table, role)?.values;
-	if (!values || values.length === 0) return void 0;
-	const value = values[Math.abs(index) % values.length];
-	return value && value !== "inherit-parent" ? value : void 0;
-}
-//#endregion
-//#region src/models.ts
-/**
-* Read `~/.dsh/pstack-models.md`, the role file `/setup-pstack` writes.
-*/
-function dshHome() {
-	return process.env.DSH_HOME || join(homedir(), ".dsh");
+/** Raised when a role name does not match the manifest. */
+var RoleNameError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "RoleNameError";
+	}
+};
+/** Normalize a role name for lookup. Case, spacing, spacing around a comma, and a trailing colon are formatting. */
+function normalizeRoleName(raw) {
+	return raw.normalize("NFC").trim().toLowerCase().replace(/\s+/g, " ").replace(/\s*,\s*/g, ", ").replace(/:+$/, "").trim();
 }
-function modelConfigPath() {
-	return join(dshHome(), "pstack-models.md");
+/** Resolve a role name, or throw a diagnostic that names the near misses. */
+function requireRole(raw) {
+	const spec = findRoleSpec(normalizeRoleName(raw));
+	if (spec !== void 0) return spec;
+	const suggestions = suggestRoles(raw);
+	const hint = suggestions.length === 0 ? "No role key is close to it." : `Closest role keys: ${suggestions.map((key) => `"${key}"`).join(", ")}.`;
+	throw new RoleNameError(`unknown pstack role ${JSON.stringify(raw)}. ${hint} Role names come from the role manifest, not from free text: pass the exact key, or omit \`role\` to inherit the parent route.`);
 }
-/**
-* Read the role file.
-*
-* A missing file is normal and means every role inherits the parent route. A
-* malformed line degrades only that line, and the issues travel with the table
-* so the tool can name them in its reply. A read failure keeps that distinction
-* explicit instead of collapsing into an empty table.
-*/
-async function loadRoleTable() {
-	try {
-		const { table, issues } = parseModelConfigWithIssues(await readFile(modelConfigPath(), "utf8"));
+function suggestRoles(raw, limit = 3) {
+	const target = normalizeRoleName(raw);
+	if (target === "") return [];
+	return ROLE_MANIFEST.map((role) => {
+		const shared = sharedTokenCount(target, role.key);
+		const distance = editDistance(target, role.key);
+		const contains = role.key.includes(target) || target.includes(role.key);
+		const score = (contains ? 1e3 : 0) + shared * 100 - distance + Math.min(role.key.length, target.length);
 		return {
-			table,
-			issues,
-			unreadable: false
-		};
-	} catch (error) {
-		if (error.code === "ENOENT") return {
-			table: /* @__PURE__ */ new Map(),
-			issues: [],
-			unreadable: false
-		};
-		return {
-			table: /* @__PURE__ */ new Map(),
-			issues: [{
-				line: 0,
-				message: `could not read ${modelConfigPath()}: ${error.message}`
-			}],
-			unreadable: true
+			key: role.key,
+			score,
+			distance,
+			shared,
+			contains
 		};
+	}).filter((candidate) => candidate.contains || candidate.shared > 0 || candidate.distance <= 4).sort((left, right) => right.score - left.score).slice(0, limit).map((candidate) => candidate.key);
+}
+function unknownRoleMessage(rawKey, key) {
+	const suggestions = suggestRoles(key);
+	const hint = suggestions.length === 0 ? "no role key is close to it" : `closest role keys: ${suggestions.map((candidate) => `"${candidate}"`).join(", ")}`;
+	return `unknown role ${JSON.stringify(rawKey)} (${hint}). A line for a retired or misspelled role is reported rather than ignored.`;
+}
+function sharedTokenCount(left, right) {
+	const rightTokens = new Set(tokenize(right));
+	return [...new Set(tokenize(left))].filter((token) => rightTokens.has(token)).length;
+}
+function tokenize(value) {
+	return value.split(/[^a-z0-9]+/).filter((token) => token !== "");
+}
+/** Levenshtein distance, iterative with one row of state. */
+function editDistance(left, right) {
+	if (left === right) return 0;
+	if (left === "") return right.length;
+	if (right === "") return left.length;
+	let previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+	for (let row = 1; row <= left.length; row += 1) {
+		const current = [row];
+		for (let column = 1; column <= right.length; column += 1) {
+			const substitution = previous[column - 1] + (left[row - 1] === right[column - 1] ? 0 : 1);
+			const deletion = previous[column] + 1;
+			const insertion = current[column - 1] + 1;
+			current.push(Math.min(substitution, deletion, insertion));
+		}
+		previous = current;
+	}
+	return previous[right.length];
+}
+function stripFrontmatter(text) {
+	const normalized = text.replaceAll("\r\n", "\n");
+	if (!normalized.startsWith("---\n")) return normalized;
+	const end = normalized.indexOf("\n---", 3);
+	if (end === -1) return normalized;
+	const after = normalized.indexOf("\n", end + 1);
+	return after === -1 ? "" : normalized.slice(after + 1);
+}
+function isMissingFile(error) {
+	return typeof error === "object" && error !== null && error.code === "ENOENT";
+}
+function describeError$1(error) {
+	if (error instanceof Error) {
+		const code = error.code;
+		return typeof code === "string" ? `${code}: ${error.message}` : error.message;
 	}
+	return String(error);
 }
-//#endregion
-//#region src/subagent.ts
+// src/subagent.ts
 /**
-* `pstack_subagent`: pstack's delegation surface for DSH.
+* `pstack_subagent`: pstack's delegation entry point.
 *
-* Cursor's `Task` tool gives every spawn a `subagent_type`, a model slug, and
-* background execution. DSH splits those across `ctx.subagents` (background
-* activations), the agent preset system (composition), and the LLM adapter
-* routes (model choice). This tool joins them back into one call whose shape a
-* ported pstack skill can use unchanged.
+* One call plans one or more fresh children, validates every route and effort before the
+* first child starts, then starts them through `ctx.subagents.startActivation` with
+* parent delivery. Results arrive as completion notices; this module never polls.
 */
+/** Cordis row name, used by Loader diagnostics. */
 const name = "pstack-subagent";
-const inject = ["tools", "subagents"];
+/**
+* Delegation needs the tool registry, the subagent registry, the LLM adapters, and the
+* session directory. `agents` is not here: it is optional and read per call, so a
+* profile without it still delegates and the child simply keeps its starting effort.
+*/
+const inject = [
+	"tools",
+	"subagents",
+	"llm",
+	"workingDirectory"
+];
+/** Model-facing tool name. */
+const TOOL_NAME = "pstack_subagent";
+/** Backend used when the row does not name one. */
+const DEFAULT_SUBAGENT_PROVIDER = "spawn";
+/** The child kinds this tool knows how to brief. */
 const AGENT_KINDS = [
 	"poteto-agent",
 	"comment-sicko",
 	"general"
 ];
-const POTETO_AGENT_PATH = `${AGENTS_ROOT}poteto-agent.md`;
-const COMMENT_SICKO_PATH = `${AGENTS_ROOT}comment-sicko.md`;
-const POTETO_MODE_PATH = `${SKILLS_ROOT}poteto-mode/SKILL.md`;
-function stripFrontmatter(source) {
-	if (!source.startsWith("---")) return source;
-	const end = source.indexOf("\n---", 3);
-	return end === -1 ? source : source.slice(end + 4).replace(/^\n+/, "");
-}
-async function readAgentInstructions(kind) {
-	if (kind === "general") return "";
-	const path = kind === "poteto-agent" ? POTETO_AGENT_PATH : COMMENT_SICKO_PATH;
-	try {
-		return stripFrontmatter(await readFile(path, "utf8"));
-	} catch {
-		return "";
+const DEFAULT_CONFIG = { provider: DEFAULT_SUBAGENT_PROVIDER };
+/** Raised for a configuration or argument problem, before any child starts. */
+var DelegationError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "DelegationError";
+	}
+};
+/** Raised when a child starts but a later entry in the same call fails. */
+var PartialDelegationError = class extends DelegationError {
+	startedChildren;
+	constructor(message, startedChildren) {
+		super(message);
+		this.name = "PartialDelegationError";
+		this.startedChildren = startedChildren;
 	}
+};
+function isNonEmptyString(value) {
+	return typeof value === "string" && value.trim() !== "";
 }
-/**
-* Build the child prompt. A pstack delegate must read `poteto-mode` first, and
-* the parent normally passes its absolute path. When the parent omits it, this
-* fallback keeps the delegate from drifting into general-purpose style.
-*/
-function composePrompt(input) {
-	if (input.kind === "general") return input.prompt;
-	const path = input.potetoModePath ?? POTETO_MODE_PATH;
-	return [
-		input.agentInstructions.trim(),
-		`Parent task label: ${input.description}`,
-		`Read \`${path}\` in full before any work, including its inline Principles index. Navigate to a leaf \`principle-*\` skill whenever you apply that principle.`,
-		input.prompt.trim()
-	].filter(Boolean).join("\n\n");
+function isNonNegativeSafeInteger(value) {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
 }
 /**
-* Resolve the `role` argument against the shipped role table, explaining a miss
-* instead of swallowing it.
+* Validate the row configuration without a Schemastery dependency.
 *
-* A missing file is normal. A configured-but-unmatched role is not: it means a
-* skill and `~/.dsh/pstack-models.md` disagree, and the child would silently run
-* on the parent route. The tool reply says so, so the parent can fix the file or
-* report the miss rather than believing the route applied.
+* A typo must fail at activation rather than at the first delegation, and an omitted
+* `config` must be valid. Cordis passes the raw mapping because this row exports no
+* `Config` object; callers that object as `config` are still checked here.
 */
-async function resolveRoleArg(role) {
-	if (!role) return {
-		route: void 0,
-		notes: []
+function normalizeConfig(value) {
+	if (value === void 0 || value === null) return DEFAULT_CONFIG;
+	if (typeof value !== "object" || Array.isArray(value)) throw new Error("pstack-subagent: config must be a mapping");
+	const record = value;
+	for (const key of Object.keys(record)) if (key !== "provider" && key !== "maxDepth") throw new Error(`pstack-subagent: unknown config field "${key}"`);
+	const provider = record["provider"];
+	if (provider !== void 0 && !isNonEmptyString(provider)) throw new Error("pstack-subagent: provider must be a non-empty string");
+	const maxDepth = record["maxDepth"];
+	if (maxDepth !== void 0 && !isNonNegativeSafeInteger(maxDepth)) throw new Error("pstack-subagent: maxDepth must be a non-negative safe integer");
+	return {
+		provider: isNonEmptyString(provider) ? provider : DEFAULT_SUBAGENT_PROVIDER,
+		...isNonNegativeSafeInteger(maxDepth) ? { maxDepth } : {}
 	};
-	const { table, issues, unreadable } = await loadRoleTable();
-	if (lookupRole(table, role)) {
-		const notes = [];
-		for (const issue of issues) if (issue.line === 0) notes.push(issue.message);
+}
+/** The preset id behind each pstack agent kind. `general` joins the parent preset. */
+const AGENT_PRESETS = {
+	"poteto-agent": "poteto-agent",
+	"comment-sicko": "comment-sicko"
+};
+/** The preset a child of this kind must mount, or undefined to join the parent preset. */
+function agentPresetFor(agent) {
+	return agent === "general" ? void 0 : AGENT_PRESETS[agent];
+}
+/** Compose the self-contained prompt one child receives. */
+function composeChildPrompt(input) {
+	const sections = [];
+	const injected = input.injectedPaths ?? [];
+	if (injected.length > 0) sections.push([
+		"Absolute paths injected by `pstack_subagent`. Read them directly; do not search a plugin directory.",
+		"",
+		...injected.map((entry) => `- ${entry.label}: \`${entry.path}\``)
+	].join("\n"));
+	if (sections.length === 0) return input.task;
+	sections.push(`Task:\n\n${input.task}`);
+	return sections.join("\n\n---\n\n");
+}
+/** Validate every required model-facing argument. Null declines an optional setting. */
+function parseDelegationArgs(raw) {
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) throw new DelegationError("arguments must be an object");
+	const record = raw;
+	const known = [
+		"description",
+		"prompt",
+		"agent",
+		"role",
+		"roleIndex",
+		"reasoningEffort",
+		"cwd",
+		"maxDepth"
+	];
+	for (const key of known) if (!Object.hasOwn(record, key)) throw new DelegationError(`missing required argument "${key}"; every argument must be passed explicitly`);
+	for (const key of Object.keys(record)) if (!known.includes(key)) throw new DelegationError(`unknown argument "${key}"; accepted arguments are ${known.join(", ")}`);
+	const description = record["description"];
+	if (!isNonEmptyString(description)) throw new DelegationError("description must be a non-empty string: it becomes the child label");
+	const prompt = record["prompt"];
+	if (!isNonEmptyString(prompt)) throw new DelegationError("prompt must be a non-empty string");
+	const agent = record["agent"];
+	if (typeof agent !== "string" || !AGENT_KINDS.includes(agent)) throw new DelegationError(`agent must be one of ${AGENT_KINDS.join(", ")}; choose explicitly, and never pass a DSH agent preset id.`);
+	const role = record["role"];
+	if (role !== null && !isNonEmptyString(role)) throw new DelegationError("role must be a non-empty string or null");
+	const cwd = record["cwd"];
+	if (cwd !== null && !isNonEmptyString(cwd)) throw new DelegationError("cwd must be a non-empty string or null");
+	const maxDepth = record["maxDepth"];
+	if (!isNonNegativeSafeInteger(maxDepth)) throw new DelegationError("maxDepth must be a non-negative safe integer");
+	const roleIndex = record["roleIndex"];
+	if (roleIndex !== null && !isNonNegativeSafeInteger(roleIndex)) throw new DelegationError("roleIndex must be a non-negative safe integer or null");
+	if (roleIndex !== null && role === null) throw new DelegationError("roleIndex requires a non-null role");
+	const requestedEffort = record["reasoningEffort"];
+	if (requestedEffort !== null && !isNonEmptyString(requestedEffort)) throw new DelegationError("reasoningEffort must be a non-empty string or null");
+	if (typeof requestedEffort === "string" && /\s/.test(requestedEffort.trim())) throw new DelegationError(`reasoningEffort ${JSON.stringify(requestedEffort)} contains whitespace. An effort is one token, exactly as the model advertises it.`);
+	return {
+		description,
+		prompt,
+		agent,
+		role,
+		cwd,
+		maxDepth,
+		roleIndex,
+		reasoningEffort: requestedEffort?.trim() ?? null
+	};
+}
+/** Route text as reported to the model. */
+function routeLabel(route, effortOverride) {
+	const effort = effectiveEffort(route, effortOverride);
+	const base = route.kind === "inherit" ? "inherit-parent" : `${route.provider}/${route.model}`;
+	return effort === void 0 ? base : `${base} [${effort}]`;
+}
+/** Take the smallest of the requested depth, this row's cap, and the Host setting. */
+function resolveDelegationDepth(configured, requested, hostLimit) {
+	if (requested !== void 0 && !isNonNegativeSafeInteger(requested)) throw new DelegationError("maxDepth must be a non-negative safe integer");
+	if (configured !== void 0 && requested !== void 0 && requested > configured) throw new DelegationError(`maxDepth ${requested} exceeds this row's configured cap of ${configured}. Lower the request or raise \`pstack-subagent\` config.maxDepth.`);
+	const candidates = [
+		configured,
+		requested,
+		hostLimit
+	].filter((value) => value !== void 0);
+	return candidates.length === 0 ? void 0 : Math.min(...candidates);
+}
+/** Resolve the role file, routes, prompt, and depth into one plan. Pure of service calls. */
+function planDelegation(args, runtime, config = DEFAULT_CONFIG) {
+	const rolePath = modelsFilePath(runtime.dshHome);
+	const roleFile = readRoleConfiguration(rolePath);
+	if (roleFile.status === "unreadable") throw new DelegationError(`the pstack role file at ${rolePath} exists but cannot be read (${roleFile.reason}). Fix its permissions or delete it, which makes every role inherit the parent route.`);
+	const diagnostics = [];
+	if (roleFile.status === "loaded") for (const issue of roleFile.issues) diagnostics.push(`${rolePath}${issue.line === void 0 ? "" : `:${issue.line}`}: ${issue.message}`);
+	let selection;
+	let roleSpec;
+	if (args.role !== null) {
+		roleSpec = requireRole(args.role);
+		const entry = roleFile.status === "loaded" ? roleFile.roles.get(roleSpec.key) : void 0;
+		selection = selectRoleRoutes(roleSpec, entry, args.roleIndex ?? void 0);
+	}
+	const routes = selection?.routes ?? [{ kind: "inherit" }];
+	const roleName = roleSpec?.key ?? "(none)";
+	if (selection !== void 0) {
+		if (!selection.configured) diagnostics.push(`role "${selection.role.key}" has no line in ${rolePath}, so it inherits the parent route. Add a line to route it explicitly.`);
+		if (selection.mode === "selected") diagnostics.push(`role "${selection.role.key}" holds ${selection.total} entries and is not an automatic panel; entry ${(selection.roleIndex ?? 0) + 1} was selected. Pass \`roleIndex\` to choose another.`);
+		if (selection.role.key === "swarm workers") diagnostics.push("role \"swarm workers\" is a list, not a panel: its first entry is the default route for every worker, and `roleIndex` gives one race arm another entry. Each worker still needs its own pstack_subagent call.");
+	}
+	const prompt = composeChildPrompt({
+		injectedPaths: args.agent === "poteto-agent" ? [{
+			label: "`poteto-mode` SKILL.md",
+			path: POTETO_MODE_SKILL_PATH
+		}] : [],
+		task: args.prompt
+	});
+	const agentPreset = agentPresetFor(args.agent);
+	const depth = resolveDelegationDepth(config.maxDepth, args.maxDepth, void 0);
+	const total = routes.length;
+	const children = routes.map((route, index) => {
+		const agentOptions = agentOptionsFor(route, args.reasoningEffort ?? void 0);
+		const effort = effectiveEffort(route, args.reasoningEffort ?? void 0);
 		return {
-			route: resolveRole(table, role),
-			notes
+			index,
+			total,
+			label: total > 1 ? `${args.description} [${roleName} ${index + 1}/${total}]` : args.description,
+			agent: args.agent,
+			role: roleName,
+			route,
+			routeLabel: routeLabel(route, args.reasoningEffort ?? void 0),
+			...effort === void 0 ? {} : { effort },
+			...agentOptions === void 0 ? {} : { agentOptions },
+			...agentPreset === void 0 ? {} : { agentPreset },
+			...args.cwd === null ? {} : { cwd: args.cwd },
+			...depth === void 0 ? {} : { maxDepth: depth }
 		};
+	});
+	if (args.reasoningEffort !== null) {
+		const overwritten = routes.filter((route) => route.kind === "route" && route.effort !== void 0 && route.effort !== args.reasoningEffort);
+		if (overwritten.length > 0) diagnostics.push(`reasoningEffort "${args.reasoningEffort}" overrides the effort this call's role line names (${overwritten.map((route) => routeLabel(route)).join(", ")}). The role line is a starting level; pass no reasoningEffort to keep it.`);
 	}
-	const near = findNearMisses(table, role);
-	const lines = [];
-	if (unreadable) lines.push(`pstack: ${modelConfigPath()} could not be read; the child inherits the parent route.`);
-	else if (table.size === 0) lines.push(`pstack: no role table at ${modelConfigPath()}; the child inherits the parent route. Run /setup-pstack to configure roles.`);
-	else {
-		lines.push(`pstack: role "${role}" is not in ${modelConfigPath()}; the child inherits the parent route.`);
-		if (near.length > 0) lines.push(`pstack: did you mean ${near.map((n) => `"${n}"`).join(" or ")}?`);
-	}
+	addPanelDiagnostics(children, roleName, selection, rolePath, diagnostics);
 	return {
-		route: void 0,
-		notes: lines
+		agent: args.agent,
+		prompt,
+		provider: config.provider,
+		role: roleName,
+		mode: selection?.mode ?? "single",
+		...selection?.roleIndex === void 0 ? {} : { roleIndex: selection.roleIndex },
+		roleTotal: selection?.total ?? 1,
+		...args.reasoningEffort === null ? {} : { reasoningEffort: args.reasoningEffort },
+		children,
+		diagnostics
 	};
 }
+function addPanelDiagnostics(children, roleName, selection, rolePath, diagnostics) {
+	if (selection === void 0 || selection.mode !== "panel") return;
+	if (children.length === 1) {
+		diagnostics.push(`panel "${roleName}" has one configured entry, so this call started one child and claims no model diversity. Add entries to ${rolePath} for a real panel.`);
+		return;
+	}
+	const distinct = new Set(children.map((child) => child.routeLabel));
+	if (distinct.size > 1) return;
+	diagnostics.push(`all ${children.length} entries of panel "${roleName}" resolve to the same route (${[...distinct][0]}), so these children are not a cross-model review.`);
+}
+/** Check the backend can enforce what this call asks for. */
+function assertProviderCapabilities(capabilities, providerName, asks) {
+	const missing = [];
+	if (asks.agentOptions && !capabilities.agentOptions) missing.push("agentOptions");
+	if (asks.agentPreset && !capabilities.agentPreset) missing.push("agentPreset");
+	if (asks.maxDepth && !capabilities.depthLimit) missing.push("maxDepth");
+	if (missing.length === 0) return;
+	throw new DelegationError(`subagent provider "${providerName}" does not support ${missing.join(", ")}. Change the route to \`inherit-parent\`, drop the unsupported argument, or configure a backend that supports it.`);
+}
+/**
+* Validate every route and effort before anything starts. An inherit-parent entry with
+* no effort carries no agentOptions and is skipped; an override on an inherit route is
+* validated against the parent's live route.
+*/
+async function preflightRoutes(llm, parent, children, roleName, effortOverride, signal) {
+	for (const child of children) {
+		if (child.agentOptions === void 0) continue;
+		if (child.route.kind === "inherit") {
+			const effort = effortOverride;
+			try {
+				await validateEffortFor(llm, void 0, effort, parent, signal);
+			} catch (error) {
+				throw new DelegationError(`role ${roleName} inherits the parent route, and reasoningEffort "${effort}" failed preflight there: ${describeError(error)} Pass null for reasoningEffort, or name a role whose line holds an exact route.`);
+			}
+			continue;
+		}
+		const route = child.route;
+		try {
+			await llm.resolveCallConfig({
+				provider: route.provider,
+				model: route.model,
+				...child.effort === void 0 ? {} : { reasoningEffort: child.effort }
+			}, signal);
+		} catch (error) {
+			throw new DelegationError(`role ${roleName} resolves to ${child.routeLabel}, which failed route preflight: ${describeError(error)}. Check the route in ${modelsFilePath("$DSH_HOME")} against the providers this deployment serves.`);
+		}
+	}
+}
 /**
-* Turn a resolved role into the `agentOptions` a child activation carries.
+* Resolve and validate one child's `cwd`.
 *
-* This is the only place a `Route` becomes a provider request. Keeping it a
-* pure function lets a test assert the exact options without starting a child,
-* which is where a role-to-route bug would otherwise stay invisible until a
-* live delegation picked the wrong model.
+* A child may run inside the session directory or inside an explicitly separate Git
+* worktree. Anything else is refused: this tool does not create isolation, so it will
+* not promise one.
 */
-function routeToAgentOptions(route) {
-	if (!route) return void 0;
+function resolveChildCwd(requested, sessionRoot) {
+	if (requested === void 0) return void 0;
+	const resolved = isAbsolute(requested) ? resolve(requested) : resolve(sessionRoot, requested);
+	let isDirectory = false;
+	try {
+		isDirectory = statSync(resolved).isDirectory();
+	} catch {
+		isDirectory = false;
+	}
+	if (!isDirectory) throw new DelegationError(`cwd ${resolved} does not exist or is not a directory`);
+	if (isWithin(sessionRoot, resolved) || isGitWorktree(resolved)) return resolved;
+	throw new DelegationError(`cwd ${resolved} is outside this session's directory (${sessionRoot}) and is not a separate Git worktree. Pass a path inside the session directory, or create a worktree first and pass its checkout.`);
+}
+function isWithin(root, target) {
+	const rel = relative(root, target);
+	return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+}
+function isGitWorktree(directory) {
+	return existsSync(join(directory, ".git"));
+}
+/**
+* Start the planned children. Everything rejectable has already been rejected; a
+* failure at entry N keeps children 1..N-1 running and reports their ids.
+*/
+async function startPlannedChildren(parent, plan, runtime, config, signal) {
+	const provider = runtime.subagents.getProvider(plan.provider);
+	if (provider === void 0) {
+		const available = runtime.subagents.list();
+		throw new DelegationError(`subagent provider "${plan.provider}" is not registered; registered providers: ${available.length === 0 ? "(none)" : available.join(", ")}.`);
+	}
+	const hostLimit = runtime.subagents.resolveMaxDepth(config.maxDepth);
+	const effectiveDepth = resolveDelegationDepth(config.maxDepth, plan.children[0]?.maxDepth, hostLimit);
+	assertProviderCapabilities(provider.capabilities, plan.provider, {
+		agentOptions: plan.children.some((child) => child.agentOptions !== void 0),
+		agentPreset: plan.children.some((child) => child.agentPreset !== void 0),
+		maxDepth: effectiveDepth !== void 0
+	});
+	const sessionRoot = await runtime.workingDirectory.ensure(parent, signal);
+	const children = plan.children.map((child) => ({
+		...child,
+		...effectiveDepth === void 0 ? {} : { maxDepth: effectiveDepth },
+		cwd: resolveChildCwd(child.cwd, sessionRoot)
+	}));
+	await preflightRoutes(runtime.llm, parent, children, plan.role, plan.reasoningEffort, signal);
+	if (runtime.subagents.getProvider(plan.provider) !== provider) throw new DelegationError(`subagent provider "${plan.provider}" changed while the child routes were being resolved; retry the delegation`);
+	const started = [];
+	const diagnostics = [...plan.diagnostics];
+	for (const child of children) {
+		signal.throwIfAborted();
+		try {
+			const activation = await runtime.subagents.startActivation({
+				provider: plan.provider,
+				label: child.label,
+				request: {
+					prompt: [{
+						type: "text",
+						text: plan.prompt
+					}],
+					parent,
+					...child.agentPreset === void 0 ? {} : { agentPreset: child.agentPreset },
+					...child.cwd === void 0 ? {} : { cwd: child.cwd },
+					...child.agentOptions === void 0 ? {} : { agentOptions: child.agentOptions },
+					...child.maxDepth === void 0 ? {} : { maxDepth: child.maxDepth }
+				},
+				signal,
+				delivery: "parent"
+			});
+			const target = runtime.agents === void 0 ? void 0 : runtime.agents.get(activation.childId);
+			if (target === void 0) diagnostics.push(`child ${activation.childId} has no live local Agent handle, so it cannot change its own reasoning effort with \`${SET_EFFORT_TOOL}\`. It runs at ${child.effort === void 0 ? "the adapter default" : `"${child.effort}"`} for its whole life.`);
+			else installEffortControl(target, runtime.llm);
+			started.push({
+				childId: activation.childId,
+				label: child.label,
+				agent: child.agent,
+				role: child.role,
+				route: child.routeLabel,
+				...child.effort === void 0 ? {} : { effort: child.effort },
+				...child.maxDepth === void 0 ? {} : { maxDepth: child.maxDepth }
+			});
+		} catch (error) {
+			if (started.length === 0) throw new DelegationError(`starting the ${plan.role === "(none)" ? "child" : `"${plan.role}" child`} "${child.label}" (${child.routeLabel}) failed: ${describeError(error)}`);
+			throw new PartialDelegationError(`starting entry ${child.index + 1} of ${child.total} for role "${plan.role}" (${child.label}, ${child.routeLabel}) failed: ${describeError(error)}. The ${started.length} already started: ${started.map((record) => `${record.childId} (${record.label})`).join(", ")}. Those children are still running and are not rolled back.`, started);
+		}
+	}
 	return {
-		provider: route.provider,
-		model: route.model,
-		...route.reasoningEffort ? { reasoningEffort: ReasoningEffortId(route.reasoningEffort) } : {}
+		kind: started.length === 1 ? "activation" : "activations",
+		children: started,
+		diagnostics
 	};
 }
-/** Tool definition over injected dependencies; `apply` supplies the runtime. */
-function createPstackTool(deps) {
-	return defineTool({
-		name: deps.toolName ?? "pstack_subagent",
-		description: "Delegate a self-contained task to a pstack subagent. Use `agent: \"poteto-agent\"` for code-writing delegates and helper tasks spawned inside a /poteto-mode playbook step. Use `agent: \"general\"` for workflow reviewers such as how, why, arena, swarm, interrogate, and reflect. Use `agent: \"comment-sicko\"` only through /no-comments. Pass `role` to select the route configured in ~/.dsh/pstack-models.md; omit it to inherit the parent route. The call returns the child id immediately and the runtime reports the final answer in a completion notice.",
-		parameters: {
+/** Full delegation: plan, validate, start. */
+async function delegate(parent, args, runtime, config = DEFAULT_CONFIG, signal = new AbortController().signal) {
+	return startPlannedChildren(parent, planDelegation(args, runtime, config), runtime, config, signal);
+}
+const TOOL_DESCRIPTION = [
+	"Delegate self-contained work to one or more fresh child agents.",
+	"",
+	"Every argument is required. Pass null for role, roleIndex, reasoningEffort, or cwd when that",
+	"setting is not used. Choose agent explicitly. maxDepth is a non-negative integer. No argument",
+	"has an implicit default.",
+	"",
+	"Returns the id of every child it started plus the route each one resolved. The children run",
+	"in the background: their results arrive later as completion notices in this conversation.",
+	"Never wait or poll for them, and keep working on something useful meanwhile.",
+	"",
+	"`agent` picks a DSH agent preset: `poteto-agent` mounts the pstack implementation delegate",
+	"and receives the absolute path of the poteto-mode instructions; `comment-sicko` mounts the",
+	"read-only comment reviewer; `general` joins the parent preset with no pstack persona.",
+	"",
+	"`role` selects a configured pstack role and therefore the child's model route and reasoning",
+	"effort. The role names come from the pstack role manifest, not this schema. Null inherits the",
+	"parent route. Automatic panel roles start one child per configured entry.",
+	"",
+	"`reasoningEffort` raises or lowers the effort for this delegation alone, using a token the",
+	"target model advertises. An unsupported value fails the call before any child starts,",
+	"including every entry of a panel. Null keeps the role line's starting effort. A running child",
+	"can change its own effort with `set_reasoning_effort`, which applies from its next step.",
+	"",
+	"Every prompt is a fresh child that does not see this conversation, so include everything it",
+	"needs. A child's own summary is not evidence: review its diff or artifacts yourself."
+].join("\n");
+function buildParameters() {
+	return {
+		type: "object",
+		additionalProperties: false,
+		properties: {
 			description: {
 				type: "string",
-				description: "A short (3-5 word) description of the delegated task, for display.",
-				required: true
+				description: "A short 3-5 word label for the child, shown in list_agents and its notices."
 			},
 			prompt: {
 				type: "string",
-				description: "The complete, self-contained task for the subagent. It does not share this conversation, so include context, file pointers, constraints, and the check that proves the work.",
-				required: true
+				description: "The complete, self-contained brief. The child does not see this conversation, so include the task, every prior directive, and the paths or branches it needs."
 			},
 			agent: {
 				type: "string",
-				enum: AGENT_KINDS,
-				description: "poteto-agent (default) for pstack delegates; general for workflow reviewers; comment-sicko for comment review."
+				enum: [...AGENT_KINDS],
+				description: "Required child preset: \"poteto-agent\" for pstack implementation delegates, \"comment-sicko\" for the read-only comment reviewer, or \"general\" to join the parent preset."
 			},
 			role: {
-				type: "string",
-				description: "Role line in ~/.dsh/pstack-models.md, such as \"feature, refactoring\" or \"judgment and prose\". Omit to inherit the parent route."
+				type: ["string", "null"],
+				description: "Required pstack role key, matched exactly. It selects the child's model route and effort. Null inherits the parent route."
 			},
 			cwd: {
-				type: "string",
-				description: "Initial child working directory. Omit to inherit the parent directory."
+				type: ["string", "null"],
+				description: "Required initial working directory, inside this session's directory or a separate Git worktree. Relative paths resolve against this session's directory. Null inherits the session directory."
+			},
+			maxDepth: {
+				type: "integer",
+				description: "Required non-negative delegation-depth limit. It can only lower this row's configured cap."
+			},
+			roleIndex: {
+				type: ["integer", "null"],
+				description: "Required entry index for a list-valued role that is not an automatic panel, 0 or greater. Requires a non-null role. Null selects the first entry."
+			},
+			reasoningEffort: {
+				type: ["string", "null"],
+				description: "Required reasoning-effort override for every child this call starts. Use one token the target model advertises, or null to keep the role line's starting effort. An unknown token fails the whole call before any child starts."
+			}
+		},
+		required: [
+			"description",
+			"prompt",
+			"agent",
+			"role",
+			"roleIndex",
+			"reasoningEffort",
+			"cwd",
+			"maxDepth"
+		]
+	};
+}
+const OUTPUT_SCHEMA = {
+	type: "object",
+	additionalProperties: false,
+	properties: {
+		kind: {
+			type: "string",
+			enum: ["activation", "activations"],
+			description: "How many children this call started."
+		},
+		children: {
+			type: "array",
+			description: "One record per started child, in start order.",
+			items: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					childId: {
+						type: "string",
+						description: "The child session id."
+					},
+					label: {
+						type: "string",
+						description: "The label this call gave the child."
+					},
+					agent: {
+						type: "string",
+						description: "The child brief type."
+					},
+					role: {
+						type: "string",
+						description: "The role key, or `(none)`."
+					},
+					route: {
+						type: "string",
+						description: "`inherit-parent` or `<provider>/<model> [effort]`."
+					},
+					effort: {
+						type: "string",
+						description: "The reasoning effort this child runs at, when one applies."
+					},
+					maxDepth: {
+						type: "integer",
+						description: "The delegation-depth cap the child received."
+					}
+				},
+				required: [
+					"childId",
+					"label",
+					"agent",
+					"role",
+					"route"
+				]
 			}
 		},
+		diagnostics: {
+			type: "array",
+			description: "Configuration notes, including a panel whose entries share one route.",
+			items: { type: "string" }
+		}
+	},
+	required: [
+		"kind",
+		"children",
+		"diagnostics"
+	]
+};
+/** Render one delegation result for the model. */
+function renderDelegationResult(result) {
+	const lines = [
+		result.kind === "activation" ? `started 1 child: ${result.children[0]?.childId ?? "(none)"}` : `started ${result.children.length} children:`,
+		...result.children.map((child) => `- ${child.childId} (${child.label}) agent=${child.agent} role=${child.role} route=${child.route}${child.effort === void 0 ? "" : ` effort=${child.effort}`}${child.maxDepth === void 0 ? "" : ` maxDepth=${child.maxDepth}`}`),
+		"Results arrive as completion notices; do not poll for them. Each child can change its own",
+		"effort from its next step with `set_reasoning_effort`."
+	];
+	if (result.diagnostics.length > 0) lines.push("", "Diagnostics:", ...result.diagnostics.map((diagnostic) => `- ${diagnostic}`));
+	return lines.join("\n");
+}
+/** Build the model-facing tool for one row. */
+function createPstackSubagentTool(runtime, config = DEFAULT_CONFIG) {
+	return {
+		name: TOOL_NAME,
+		description: TOOL_DESCRIPTION,
+		parameters: buildParameters(),
 		output: {
-			schema: { type: "string" },
+			schema: OUTPUT_SCHEMA,
 			render: (_args, value) => [{
 				type: "text",
-				text: value
+				text: renderDelegationResult(value)
 			}]
 		},
-		async execute(args, exec) {
+		isConcurrencySafe: () => true,
+		async execute(rawArgs, exec) {
 			const parent = exec.agent;
-			if (!parent) throw new Error("pstack_subagent requires an agent context");
-			const kind = args.agent ?? deps.defaultAgent ?? "poteto-agent";
-			const agentInstructions = await deps.loadAgent(kind);
-			const prompt = composePrompt({
-				kind,
-				description: args.description,
-				prompt: args.prompt,
-				agentInstructions,
-				...deps.potetoModePath ? { potetoModePath: deps.potetoModePath } : {}
-			});
-			const { route, notes } = await deps.loadRole(args.role);
-			const started = `started subagent ${(await deps.start({
-				parent,
-				label: args.description,
-				prompt: [{
-					type: "text",
-					text: prompt
-				}],
-				signal: exec.signal,
-				route,
-				cwd: args.cwd
-			})).childId}`;
-			return notes.length > 0 ? [started, ...notes].join("\n") : started;
+			if (parent === void 0) throw new DelegationError("pstack_subagent needs a calling Agent, and exec.agent was undefined.");
+			return await delegate(parent, parseDelegationArgs(rawArgs), runtime, config, exec.signal);
 		}
-	});
+	};
 }
-/**
-* Build the provider-facing activation request for one child.
-*
-* A role is resolved once, at delegation time, into concrete provider options.
-* The child inherits the parent route when the role is absent or resolves to
-* `inherit-parent`, which is why the field is omitted rather than set to a
-* placeholder.
-*/
-function buildActivationRequest(input) {
-	const options = routeToAgentOptions(input.route);
+/** Build the runtime a real Host call reads. */
+function hostRuntime(ctx, getAgentRegistry = () => void 0) {
 	return {
-		parent: input.parent,
-		prompt: input.prompt,
-		...input.cwd ? { cwd: input.cwd } : {},
-		...options ? { agentOptions: options } : {}
+		subagents: ctx.subagents,
+		llm: ctx.llm,
+		workingDirectory: ctx.workingDirectory,
+		get agents() {
+			return getAgentRegistry();
+		},
+		dshHome: resolveDshHome()
 	};
 }
-/**
-* Mount the tool. `ctx.subagents` owns child lifecycle; this row only supplies
-* the pstack-specific shape (agent preambles and role routes) on top.
-*/
-function apply(ctx, config = {}) {
-	const providerName = config.provider ?? "spawn";
-	const tool = createPstackTool({
-		async start({ parent, label, prompt, signal, route, cwd }) {
-			const activation = await ctx.subagents.startActivation({
-				provider: providerName,
-				label,
-				signal,
-				delivery: "parent",
-				request: buildActivationRequest({
-					parent,
-					prompt,
-					route,
-					cwd
-				})
-			});
-			return { childId: String(activation.childId) };
-		},
-		loadAgent: readAgentInstructions,
-		loadRole: resolveRoleArg,
-		potetoModePath: POTETO_MODE_PATH,
-		...config.defaultAgent ? { defaultAgent: config.defaultAgent } : {},
-		...config.toolName ? { toolName: config.toolName } : {}
-	});
-	ctx.tools.register(tool);
+/** Register `pstack_subagent` for this row. */
+function apply(ctx, config) {
+	const resolved = normalizeConfig(config);
+	const runtime = hostRuntime(ctx, () => ctx.get?.("agents"));
+	ctx.tools.register(createPstackSubagentTool(runtime, resolved));
+}
+function describeError(error) {
+	if (error instanceof Error) {
+		const code = error.code;
+		const suffix = typeof code === "string" ? ` (${code})` : "";
+		return `${error.message}${suffix}`;
+	}
+	return String(error);
 }
-//#endregion
-export { apply, buildActivationRequest, composePrompt, createPstackTool, inject, name, readAgentInstructions, resolveRoleArg, routeToAgentOptions, stripFrontmatter };
-
-//# sourceMappingURL=subagent.mjs.map
+export { AGENT_KINDS, AGENT_PRESETS, DEFAULT_SUBAGENT_PROVIDER, DelegationError, PartialDelegationError, TOOL_NAME, agentPresetFor, apply, assertProviderCapabilities, composeChildPrompt, createPstackSubagentTool, delegate, hostRuntime, inject, name, normalizeConfig, parseDelegationArgs, planDelegation, renderDelegationResult, resolveChildCwd, resolveDelegationDepth, routeLabel, startPlannedChildren };