dsh-pstack 0.2.0-beta.3 → 0.2.1

package/dist/subagent.mjs

@@ -1,7 +1,7 @@
-import { a as POTETO_MODE_SKILL_PATH } from "./paths-BT77khwm.mjs";
+import { a as POTETO_MODE_SKILL_PATH } from "./paths-yji9SNak.mjs";
+import { a as selectRoleRoutes, i as resolveDshHome, n as readRoleConfiguration, r as requireRole, t as modelsFilePath } from "./role-config-a4JpVdc-.mjs";
 import { isAbsolute, join, relative, resolve } from "node:path";
-import { existsSync, readFileSync, statSync } from "node:fs";
-import { homedir } from "node:os";
+import { existsSync, statSync } from "node:fs";
 // src/internal/effort.ts
 /** Model-facing name of the child's own control. */
 const SET_EFFORT_TOOL = "set_reasoning_effort";
@@ -30,7 +30,7 @@ async function validateEffortFor(llm, route, effort, parent, signal) {
 	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 });
+		throw new Error(`route ${target.provider}/${target.model} could not be resolved for reasoningEffort: ${describeError$1(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(", ")}.`);
@@ -83,7 +83,7 @@ function defineSetEffortTool(child, llm) {
 			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 });
+				throw new Error(`${target.provider}/${target.model} could not be resolved for reasoning effort: ${describeError$1(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(", ")}.`);
@@ -110,417 +110,10 @@ function agentOptionsFor(route, effortOverride) {
 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
-	}
-];
-/** Exact manifest lookup. Callers normalize the key first. */
-function findRoleSpec(key) {
-	return ROLE_MANIFEST.find((role) => role.key === key);
-}
-// src/internal/role-config.ts
-/**
-* 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.
-*
-* 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.
-*/
-/** 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 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,
-				message: `expected \`<role>: <value>\`, found ${JSON.stringify(trimmed)}`
-			});
-			return;
-		}
-		const rawKey = trimmed.slice(0, separator).trim();
-		const rawValue = trimmed.slice(separator + 1).trim();
-		const key = normalizeRoleName(rawKey);
-		if (key === "") {
-			issues.push({
-				line,
-				message: "the role key is empty"
-			});
-			return;
-		}
-		const spec = findRoleSpec(key);
-		if (spec === void 0) {
-			issues.push({
-				line,
-				message: unknownRoleMessage(rawKey, key)
-			});
-			return;
-		}
-		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: `${rawKey}: ${issue}`
-		});
-		if (parsed.routes.length === 0) return;
-		const previous = roles.get(spec.key);
-		if (previous !== void 0) issues.push({
-			line,
-			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 {
-		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";
-	}
-};
-/**
-* Expand one role into the routes this call starts.
-*
-* 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 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 {
-		role: spec,
-		mode: "single",
-		configured: true,
-		routes: [entry.routes[0]],
-		total: entry.routes.length
-	};
-}
-/** Keys of the list-valued roles, including the automatic panels. */
-function listRoleKeys() {
-	return ROLE_MANIFEST.filter((role) => role.shape === "list").map((role) => role.key);
-}
-/** 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();
-}
-/** 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.`);
-}
-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 {
-			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 typeof code === "string" ? `${error.message} (${code})` : error.message;
 	}
 	return String(error);
 }
@@ -556,6 +149,13 @@ const AGENT_KINDS = [
 	"general"
 ];
 const DEFAULT_CONFIG = { provider: DEFAULT_SUBAGENT_PROVIDER };
+/**
+* Depth a child runs at when a call omits `maxDepth` or passes an unusable value.
+*
+* A child is always at least depth 1 (it is one level below its parent), so this is the
+* smallest value that can start a child while forbidding it from delegating further.
+*/
+const DEFAULT_CHILD_MAX_DEPTH = 1;
 /** Raised for a configuration or argument problem, before any child starts. */
 var DelegationError = class extends Error {
 	constructor(message) {
@@ -621,22 +221,36 @@ function composeChildPrompt(input) {
 	sections.push(`Task:\n\n${input.task}`);
 	return sections.join("\n\n---\n\n");
 }
+const DELEGATION_ARGUMENT_KEYS = [
+	"description",
+	"prompt",
+	"agent",
+	"role",
+	"roleIndex",
+	"reasoningEffort",
+	"cwd",
+	"maxDepth"
+];
+/**
+* Keys a call must pass. `maxDepth` is accepted but not required: a missing or unusable
+* value resolves to `DEFAULT_CHILD_MAX_DEPTH` instead of forcing the caller to guess an
+* integer, which is where the reflexive `0` came from.
+*/
+const REQUIRED_DELEGATION_ARGUMENT_KEYS = [
+	"description",
+	"prompt",
+	"agent",
+	"role",
+	"roleIndex",
+	"reasoningEffort",
+	"cwd"
+];
 /** 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(", ")}`);
+	for (const key of REQUIRED_DELEGATION_ARGUMENT_KEYS) if (!Object.hasOwn(record, key)) throw new DelegationError(`missing required argument "${key}"; every argument except maxDepth must be passed explicitly`);
+	for (const key of Object.keys(record)) if (!DELEGATION_ARGUMENT_KEYS.includes(key)) throw new DelegationError(`unknown argument "${key}"; accepted arguments are ${DELEGATION_ARGUMENT_KEYS.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"];
@@ -647,8 +261,9 @@ function parseDelegationArgs(raw) {
 	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 rawMaxDepth = record["maxDepth"];
+	const maxDepth = rawMaxDepth === void 0 ? null : rawMaxDepth;
+	if (maxDepth !== null && !isNonNegativeSafeInteger(maxDepth)) throw new DelegationError("maxDepth must be a non-negative safe integer, or null/omitted");
 	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");
@@ -674,15 +289,30 @@ function routeLabel(route, effortOverride) {
 }
 /** 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.`);
+	if (requested !== void 0 && requested !== null && !isNonNegativeSafeInteger(requested)) throw new DelegationError("maxDepth must be a non-negative safe integer or null");
+	if (configured !== void 0 && requested !== void 0 && requested !== null && 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);
+	].filter((value) => value !== void 0 && value !== null);
 	return candidates.length === 0 ? void 0 : Math.min(...candidates);
 }
+/**
+* Turn the per-call `maxDepth` request into an effective depth request.
+*
+* A child is always at least depth 1, so `0` can never start one: it is reported and
+* replaced with `DEFAULT_CHILD_MAX_DEPTH` rather than failing the whole call. Omitting
+* `maxDepth` (null) also uses the default, so a caller never has to guess an integer.
+*/
+function requestedChildDepth(requested, diagnostics) {
+	if (requested === null) return 1;
+	if (requested === 0) {
+		diagnostics.push(`maxDepth 0 cannot start a child (the child itself is depth 1), so this call used 1. Omit maxDepth for that default, or pass 1 or more.`);
+		return 1;
+	}
+	return requested;
+}
 /** 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);
@@ -712,7 +342,7 @@ function planDelegation(args, runtime, config = DEFAULT_CONFIG) {
 		task: args.prompt
 	});
 	const agentPreset = agentPresetFor(args.agent);
-	const depth = resolveDelegationDepth(config.maxDepth, args.maxDepth, void 0);
+	const depth = resolveDelegationDepth(config.maxDepth, requestedChildDepth(args.maxDepth, diagnostics), void 0);
 	const total = routes.length;
 	const children = routes.map((route, index) => {
 		const agentOptions = agentOptionsFor(route, args.reasoningEffort ?? void 0);
@@ -902,9 +532,11 @@ async function delegate(parent, args, runtime, config = DEFAULT_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.",
+	"Every argument is required except maxDepth. Pass null for role, roleIndex, reasoningEffort,",
+	"or cwd when that setting is not used. Choose agent explicitly. maxDepth is optional: omit it",
+	"(or pass null) for the safe default of 1, where the child exists but cannot start its own",
+	"children; pass 2 or more, within this row's configured cap, to let it delegate further. A 0 is",
+	"treated as 1, because a child is already depth 1 and 0 can never start one.",
 	"",
 	"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.",
@@ -953,28 +585,19 @@ function buildParameters() {
 				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."
+				type: ["integer", "null"],
+				description: "Optional delegation-depth cap for the child. Omit or pass null for the safe default of 1 (the child exists but cannot start its own children). Pass 2 or more, within this row's configured cap, to let it delegate further. 0 is treated as 1: a child is already depth 1, so 0 can never start one."
 			},
 			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."
+				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. Call `pstack_roles` to see which roles accept an index."
 			},
 			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"
-		]
+		required: [...REQUIRED_DELEGATION_ARGUMENT_KEYS]
 	};
 }
 const OUTPUT_SCHEMA = {
@@ -1101,4 +724,4 @@ function describeError(error) {
 	}
 	return String(error);
 }
-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 };
+export { AGENT_KINDS, AGENT_PRESETS, DEFAULT_CHILD_MAX_DEPTH, DEFAULT_SUBAGENT_PROVIDER, DELEGATION_ARGUMENT_KEYS, DelegationError, PartialDelegationError, REQUIRED_DELEGATION_ARGUMENT_KEYS, TOOL_NAME, agentPresetFor, apply, assertProviderCapabilities, composeChildPrompt, createPstackSubagentTool, delegate, hostRuntime, inject, name, normalizeConfig, parseDelegationArgs, planDelegation, renderDelegationResult, requestedChildDepth, resolveChildCwd, resolveDelegationDepth, routeLabel, startPlannedChildren };