@selesai/code 0.13.34 → 0.13.37

package/dist/extensions/jev-ask-tool.ts

@@ -13,11 +13,13 @@
  * tool's own abort signal. Every part is clipped to the route's payload budget
  * before the call, so an oversized request is trimmed rather than abstained.
  */
+import { execFile } from "node:child_process";
 import { closeSync, openSync, readSync, realpathSync, statSync } from "node:fs";
-import { basename, isAbsolute, relative, resolve } from "node:path";
+import { basename, isAbsolute, normalize, relative, resolve } from "node:path";
 import { StringEnum } from "@earendil-works/pi-ai";
 import {
 	createLocalBashOperations,
+	ensureTool,
 	type ExtensionAPI,
 	type ExtensionContext,
 	getSettingsPath,
@@ -339,6 +341,247 @@ export function renderAskAnswers(input: {
 	return [...header, ...lines, ...footer].join("\n");
 }
 
+// ---------------------------------------------------------------------------
+// jev_find: ripgrep gathers candidates, Jev judges each one
+// ---------------------------------------------------------------------------
+
+/** The file finder's registered name. */
+export const JEV_FIND_TOOL = "jev_find";
+/** ponytail: 16 nouls per request (the JevPDF batch size); raise once Jev is measured on larger blocks. */
+export const FIND_BATCH = 16;
+/** Three batches, sent in parallel, so a find costs one Jev round trip. */
+export const MAX_FIND_CANDIDATES = 48;
+const FIND_MATCH_LINES = 6;
+const FIND_DEFAULT_LIMIT = 8;
+const FIND_MIN_RELEVANCE = 0.5;
+/** Room each batch keeps for the questions and JSON scaffolding. */
+const FIND_QUESTION_RESERVE = 6 * 1024;
+
+export interface FindCandidate {
+	path: string;
+	/** Matched line numbers (pattern mode only). */
+	lines: number[];
+	/** What Jev reads: the matched lines, or the head of the file. */
+	snippet: string;
+}
+
+/** Run ripgrep with an argument list (no shell). Exit 1 is "no matches"; an overfull buffer keeps what arrived. */
+function runRg(bin: string, args: string[], cwd: string, signal: AbortSignal | undefined): Promise<string> {
+	return new Promise((done, fail) => {
+		execFile(
+			bin,
+			args,
+			{ cwd, signal, maxBuffer: 8 * 1024 * 1024, timeout: ASK_COMMAND_TIMEOUT_SECONDS * 1000 },
+			(error, stdout) => {
+				const code = error ? (error as { code?: unknown }).code : 0;
+				if (!error || code === 1 || code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") done(String(stdout));
+				else fail(error);
+			},
+		);
+	});
+}
+
+/** Filler words that would match nearly every file. */
+const FIND_STOP_WORDS = new Set(
+	"the and for with where what which when who how does did this that from into its are was can should would there file files code find implement implemented implements".split(" "),
+);
+
+/** Question words worth searching for: 3+ letters, not filler, at most eight. */
+function questionWords(question: string): string[] {
+	const words = question.toLowerCase().match(/[a-z0-9]{3,}/g) ?? [];
+	return [...new Set(words)].filter((word) => !FIND_STOP_WORDS.has(word)).slice(0, 8);
+}
+
+/** How much of each listed file is scanned for question words. */
+const FIND_SCAN_BYTES = 256 * 1024;
+const FIND_EXCERPT_LINES = 12;
+
+/**
+ * What Jev reads of a listed file: the lines holding the most distinct question words, in file
+ * order and numbered, or the head of the file when none match. A file's head is usually its
+ * doc comment, which rarely shows where the asked-about behavior lives.
+ */
+export function excerpt(text: string, words: readonly string[], maxBytes: number): { lines: number[]; snippet: string } {
+	const rows = text.split("\n");
+	const best = rows
+		.map((row, index) => {
+			const lower = row.toLowerCase();
+			return { index, count: words.filter((word) => lower.includes(word)).length };
+		})
+		.filter((hit) => hit.count > 0)
+		.sort((a, b) => b.count - a.count || a.index - b.index)
+		.slice(0, FIND_EXCERPT_LINES);
+	if (best.length === 0) return { lines: [], snippet: clip(text, maxBytes).text };
+	const inOrder = [...best].sort((a, b) => a.index - b.index);
+	const snippet = inOrder.map((hit) => `L${hit.index + 1}: ${rows[hit.index].trim().slice(0, 240)}`).join("\n");
+	// Pointers lead with the best-matching lines.
+	return { lines: best.map((hit) => hit.index + 1), snippet: clip(snippet, maxBytes).text };
+}
+
+/** Path parts (3+ letters) sharing a stem with a question word; orders a file listing before it is capped. */
+function pathOverlap(path: string, words: readonly string[]): number {
+	const parts = path.toLowerCase().match(/[a-z0-9]{3,}/g) ?? [];
+	return parts.filter((part) => words.some((word) => word.includes(part) || part.includes(word))).length;
+}
+
+/**
+ * Candidate files under `root`, most promising first. With `pattern`, the files ripgrep matches
+ * (most matches first) with their matched lines as the snippet; without it, every file ripgrep
+ * lists (question words in the path first) with the head of the file as the snippet. Respects
+ * .gitignore, and never offers a file `askPath` would refuse.
+ */
+export async function findCandidates(
+	options: { rg: string; cwd: string; root: string; question: string; pattern?: string; glob?: string; ignoreCase?: boolean },
+	snippetBytes: number,
+	signal: AbortSignal | undefined,
+): Promise<{ candidates: FindCandidate[]; total: number }> {
+	// Always name the root: with no path and a piped stdin, rg searches stdin and hangs.
+	// Paths come back as `./src/x.ts`, so they are normalized below.
+	const root = ["--", options.root];
+	const filters = [...(options.glob ? ["--glob", options.glob] : []), ...(options.ignoreCase ? ["-i"] : [])];
+	const allowed = (path: string) => "full" in askPath(path, options.cwd);
+	if (options.pattern) {
+		const out = await runRg(
+			options.rg,
+			["--null", "--line-number", "--no-heading", "--color=never", "--max-count", String(FIND_MATCH_LINES), "--max-columns", "240", ...filters, "-e", options.pattern, ...root],
+			options.cwd,
+			signal,
+		);
+		const byFile = new Map<string, { lines: number[]; text: string[] }>();
+		for (const row of out.split("\n")) {
+			const nul = row.indexOf("\0");
+			if (nul < 0) continue;
+			const path = normalize(row.slice(0, nul));
+			const match = /^(\d+):(.*)$/.exec(row.slice(nul + 1));
+			if (!match) continue;
+			const entry = byFile.get(path) ?? { lines: [], text: [] };
+			entry.lines.push(Number(match[1]));
+			entry.text.push(`L${match[1]}: ${match[2].trim()}`);
+			byFile.set(path, entry);
+		}
+		const files = [...byFile].filter(([path]) => allowed(path)).sort((a, b) => b[1].lines.length - a[1].lines.length);
+		return {
+			total: files.length,
+			candidates: files.slice(0, MAX_FIND_CANDIDATES).map(([path, entry]) => ({
+				path,
+				lines: entry.lines,
+				snippet: clip(entry.text.join("\n"), snippetBytes).text,
+			})),
+		};
+	}
+	const words = questionWords(options.question);
+	const out = await runRg(options.rg, ["--files", "--color=never", ...filters, ...root], options.cwd, signal);
+	const listed = out
+		.split("\n")
+		.filter((path) => path !== "")
+		.map((path) => normalize(path))
+		.filter(allowed);
+	const score = new Map(listed.map((path) => [path, pathOverlap(path, words)]));
+	if (listed.length > MAX_FIND_CANDIDATES && words.length > 0) {
+		// More files than Jev judges: a file scores once per distinct question word its content holds,
+		// one fixed-string ripgrep per word, in parallel.
+		const hits = await Promise.all(
+			words.map((word) =>
+				runRg(options.rg, ["-l", "-i", "-F", "--color=never", ...filters, "-e", word, ...root], options.cwd, signal),
+			),
+		);
+		for (const listing of hits) {
+			for (const raw of listing.split("\n")) {
+				const path = raw === "" ? "" : normalize(raw);
+				const current = score.get(path);
+				if (current !== undefined) score.set(path, current + 1);
+			}
+		}
+	}
+	const files = listed.map((path) => ({ path })).sort((a, b) => (score.get(b.path) ?? 0) - (score.get(a.path) ?? 0));
+	const candidates: FindCandidate[] = [];
+	for (const { path } of files.slice(0, MAX_FIND_CANDIDATES)) {
+		const file = readBounded(resolve(options.cwd, path), FIND_SCAN_BYTES);
+		if ("error" in file) continue;
+		candidates.push({ path, ...excerpt(file.text, words, snippetBytes) });
+	}
+	return { candidates, total: files.length };
+}
+
+/** One batch as a decisions request: the shared snippets as state, one noul per file. */
+export function buildFindPayload(question: string, batch: readonly FindCandidate[]): Record<string, unknown> {
+	return buildAskPayload(
+		batch.map((candidate, index) => ({
+			name: `f${index}`,
+			type: "noul" as const,
+			instructions: `Is the file "${candidate.path}" relevant to the request, judged by its excerpt in state.files?`,
+			criteria: {
+				true: "The excerpt shows this file implements, defines, configures, or directly answers the request.",
+				false: "The file only mentions related words, or is about something else.",
+			},
+		})),
+		{ request: question, files: Object.fromEntries(batch.map((candidate) => [candidate.path, candidate.snippet])) },
+	);
+}
+
+/**
+ * The batch's request, its snippets shrunk until the serialized request fits `maxBytes`: code
+ * grows under JSON escaping, so a byte budget per snippet alone does not guarantee a fit.
+ */
+export function fitFindPayload(question: string, batch: readonly FindCandidate[], maxBytes: number): Record<string, unknown> {
+	let limit = Math.max(0, ...batch.map((candidate) => Buffer.byteLength(candidate.snippet, "utf-8")));
+	for (;;) {
+		const payload = buildFindPayload(
+			question,
+			batch.map((candidate) => ({ ...candidate, snippet: clip(candidate.snippet, limit).text })),
+		);
+		if (limit < 64 || serializeJevRequest(payload, maxBytes) !== undefined) return payload;
+		limit = Math.floor(limit * 0.75);
+	}
+}
+
+/** Pointers only: path, matched lines, relevance. File contents never reach the agent. */
+export function renderFindResults(input: {
+	ranked: ReadonlyArray<FindCandidate & { relevance?: number }>;
+	total: number;
+	judged: number;
+	limit: number;
+	model: string;
+	elapsedMs: number;
+	failure?: string;
+}): string {
+	const pointer = (candidate: FindCandidate) =>
+		candidate.lines.length > 0 ? `${candidate.path}:${candidate.lines.slice(0, 4).join(",")}` : candidate.path;
+	if (input.total === 0) return "jev_find: no candidate files. Loosen `pattern`, `glob`, or `path`.";
+	const lines: string[] = [];
+	if (input.judged === 0) {
+		lines.push(
+			`jev_find: Jev did not judge (${input.failure ?? "missing"}); ${input.total} candidate file(s), unranked by relevance:`,
+			...input.ranked.slice(0, input.limit).map((candidate) => `- ${pointer(candidate)}`),
+		);
+	} else {
+		const strong = input.ranked.filter((candidate) => (candidate.relevance ?? 0) >= FIND_MIN_RELEVANCE);
+		lines.push(`jev_find: judged ${input.judged} of ${input.total} candidate file(s) via ${input.model} in ${input.elapsedMs}ms`);
+		const shown = strong.length > 0 ? strong.slice(0, input.limit) : input.ranked.slice(0, 3);
+		if (strong.length === 0) lines.push("No file is a confident match; the closest were:");
+		for (const candidate of shown) {
+			lines.push(`- ${pointer(candidate)} (${candidate.relevance === undefined ? "not judged" : candidate.relevance.toFixed(2)})`);
+		}
+		if (strong.length > shown.length) lines.push(`${strong.length - shown.length} more relevant file(s) past the limit.`);
+	}
+	if (input.total > MAX_FIND_CANDIDATES) {
+		lines.push(`${input.total - MAX_FIND_CANDIDATES} candidate(s) were not judged; narrow with \`pattern\`, \`glob\`, or \`path\`.`);
+	}
+	lines.push("Only pointers are returned; read the files you need.");
+	return lines.join("\n");
+}
+
+const JevFindParams = Type.Object({
+	question: Type.String({ description: "What you are looking for, in plain words (e.g. 'where is the retry backoff configured')." }),
+	pattern: Type.Optional(
+		Type.String({ description: "ripgrep regex to narrow candidates to files that match; omit to judge every listed file." }),
+	),
+	glob: Type.Optional(Type.String({ description: "File glob filter, e.g. '*.ts' or 'src/**/*.md'." })),
+	path: Type.Optional(Type.String({ description: "Directory to search, inside the working directory (default: '.')." })),
+	ignoreCase: Type.Optional(Type.Boolean({ description: "Case-insensitive pattern." })),
+	limit: Type.Optional(Type.Number({ description: `Most results to return (default ${FIND_DEFAULT_LIMIT}).` })),
+});
+
 // ---------------------------------------------------------------------------
 // Tool
 // ---------------------------------------------------------------------------
@@ -562,25 +805,147 @@ export default function jevAskToolExtension(pi: ExtensionAPI): void {
 		},
 	});
 
-	// Offer the tool only while Jev can answer: a tool that always fails costs the agent a turn
-	// every time it reaches for it. Checked before every run, so `/tokenin add` brings it back
+	pi.registerTool({
+		name: JEV_FIND_TOOL,
+		label: "Jev Find",
+		description: [
+			"Find which files answer a question without reading them: ripgrep gathers candidate files (those matching",
+			"`pattern`, or every file under `path` filtered by `glob`), and Jev judges each file's excerpt against",
+			"`question` in one parallel round trip. Returns ranked `path:lines (relevance)` pointers, never contents.",
+			`Judges up to ${MAX_FIND_CANDIDATES} files per call; respects .gitignore; secret-named files are never sent.`,
+		].join(" "),
+		promptSnippet: "Find the files that answer a question: ripgrep candidates ranked by Jev, pointers only",
+		promptGuidelines: [
+			"When you look for code by what it does rather than by an exact identifier you already know, call jev_find first — before grep, find, ls, or reading candidate files. One call ranks up to 48 files in about a second and returns file:line pointers; then read only the top ones. Pass `question` in plain words; add `pattern` when you know a likely identifier, `glob`/`path` to scope it.",
+			"Use grep for an exact string or identifier you already know; use jev_find when you would otherwise grep several guesses or read files to see which one is relevant.",
+		],
+		discovery: {
+			summary: "Semantic file finder: ripgrep candidates ranked by Jev relevance",
+			aliases: ["jevgrep", "find", "search", "locate"],
+			category: "Decisions",
+		},
+		parameters: JevFindParams,
+
+		async execute(_toolCallId, params, signal, _onUpdate, ctx: ExtensionContext) {
+			const text = (value: string, details: Record<string, unknown> = {}) => ({
+				content: [{ type: "text" as const, text: value }],
+				details,
+			});
+			const config = readJevAdvisoryConfig(getSettingsPath());
+			const route = config.routes.ask;
+			if (!route.enabled) {
+				return text(`jev_find is disabled (jevAdvisory.routes.ask.enabled is false in ${getSettingsPath()}).`);
+			}
+			const question = params.question?.trim() ?? "";
+			if (question === "") return text("jev_find needs a non-empty `question`.");
+
+			const rootArg = params.path?.trim() || ".";
+			const rootFull = resolve(ctx.cwd, rootArg);
+			const inside = relative(resolve(ctx.cwd), rootFull);
+			if (inside.startsWith("..") || isAbsolute(inside)) {
+				return text(`jev_find: ${rootArg} is outside the working directory.`);
+			}
+			const rg = await ensureTool("rg");
+			if (!rg) return text("jev_find needs ripgrep (rg), which is not available; use grep instead.");
+
+			const snippetBytes = Math.max(256, Math.floor((route.payloadBytes - FIND_QUESTION_RESERVE) / FIND_BATCH));
+			let found: { candidates: FindCandidate[]; total: number };
+			try {
+				found = await findCandidates(
+					{
+						rg,
+						cwd: ctx.cwd,
+						root: inside === "" ? "." : inside,
+						question,
+						pattern: params.pattern || undefined,
+						glob: params.glob || undefined,
+						ignoreCase: params.ignoreCase,
+					},
+					snippetBytes,
+					signal,
+				);
+			} catch (error) {
+				return text(`jev_find: ripgrep failed (${error instanceof Error ? error.message.split("\n")[0] : String(error)}).`);
+			}
+			const limit = Math.max(1, Math.floor(params.limit ?? FIND_DEFAULT_LIMIT));
+			const { candidates, total } = found;
+			if (candidates.length === 0) {
+				return text(renderFindResults({ ranked: [], total: 0, judged: 0, limit, model: config.model, elapsedMs: 0 }));
+			}
+
+			// Without Jev the candidates are still worth returning: the call is never wasted.
+			const connection = jevConnection(config, route);
+			const unreachable = await jevUnavailable(ctx, connection);
+			const batches: FindCandidate[][] = [];
+			for (let start = 0; start < candidates.length; start += FIND_BATCH) {
+				batches.push(candidates.slice(start, start + FIND_BATCH));
+			}
+			const started = Date.now();
+			const results = unreachable
+				? []
+				: await Promise.all(
+						batches.map((batch) =>
+							askJevAnswers(ctx, connection, {
+								payload: fitFindPayload(question, batch, route.payloadBytes),
+								maxBytes: route.payloadBytes,
+							}),
+						),
+					);
+			const elapsedMs = Date.now() - started;
+
+			const scored: Array<FindCandidate & { relevance?: number }> = [];
+			let judged = 0;
+			batches.forEach((batch, b) => {
+				const answers = results[b]?.answers ?? {};
+				batch.forEach((candidate, i) => {
+					const answer = answers[`f${i}`];
+					const relevance = isRecord(answer) && typeof answer.noul === "number" ? answer.noul : undefined;
+					if (relevance !== undefined) judged += 1;
+					scored.push({ ...candidate, ...(relevance === undefined ? {} : { relevance }) });
+				});
+			});
+			// Judged files by relevance; unjudged ones keep ripgrep's order behind them.
+			const ranked = judged > 0 ? [...scored].sort((a, b) => (b.relevance ?? -1) - (a.relevance ?? -1)) : scored;
+			const failure = unreachable ?? results.find((result) => result.failure)?.failure;
+
+			emitJevTelemetry(pi.events, "decision", {
+				route: "find",
+				outcome: judged > 0 ? "jev" : "fallback",
+				candidates: candidates.length,
+				confidence: confidenceBucket(ranked[0]?.relevance),
+				elapsedMs,
+				...(judged > 0 ? {} : { reason: failure ?? "missing" }),
+			});
+			return text(
+				renderFindResults({ ranked, total, judged, limit, model: config.model, elapsedMs, failure }),
+				// Shape only, like ask_jev: details persist in the session.
+				{ candidates: candidates.length, total, judged, elapsedMs, ...(failure ? { failure } : {}) },
+			);
+		},
+	});
+
+	// Offer the tools only while Jev can answer: a tool that always fails costs the agent a turn
+	// every time it reaches for it. Checked before every run, so `/tokenin add` brings them back
 	// without a reload. Silent on purpose: the one warning comes from whichever Jev path first
 	// needs the missing credential, not from every session of a user without a subscription.
 	// Only a removal made here is ever undone, so a loadout the user trimmed stays trimmed.
-	let hidden = false;
+	const jevTools = [ASK_JEV_TOOL, JEV_FIND_TOOL];
+	const hidden = new Set<string>();
 	pi.on("before_agent_start", async (_event, ctx) => {
 		const config = readJevAdvisoryConfig(getSettingsPath());
 		const route = config.routes.ask;
 		const offline = !route.enabled || (await jevUnavailable(ctx, jevConnection(config, route))) !== undefined;
 		const active = pi.getActiveTools();
 		if (offline) {
-			if (active.includes(ASK_JEV_TOOL)) {
-				pi.setActiveTools(active.filter((name) => name !== ASK_JEV_TOOL));
-				hidden = true;
+			const dropping = jevTools.filter((name) => active.includes(name));
+			if (dropping.length > 0) {
+				pi.setActiveTools(active.filter((name) => !dropping.includes(name)));
+				for (const name of dropping) hidden.add(name);
 			}
-		} else if (hidden) {
-			if (!active.includes(ASK_JEV_TOOL)) pi.setActiveTools([...active, ASK_JEV_TOOL]);
-			hidden = false;
+		} else if (hidden.size > 0) {
+			const restoring = [...hidden].filter((name) => !active.includes(name));
+			if (restoring.length > 0) pi.setActiveTools([...active, ...restoring]);
+			hidden.clear();
 		}
 		return undefined;
 	});

package/dist/extensions/pi-subagents/src/extension/public-execution.ts

@@ -201,17 +201,19 @@ export function normalizePublicSubagentExecution<T extends PublicSubagentExecuti
 		return { ok: false, error: "Structured single-child execution cannot be combined with workflow, workflowScript, or workflowScriptPath.", mode: "workflow" };
 	}
 	if (params.agent !== undefined || params.task !== undefined) {
-		if (typeof params.agent !== "string" || !params.agent.trim()) {
-			return { ok: false, error: "Structured single-child execution requires agent to be a non-empty string.", mode: "workflow" };
-		}
 		if (params.task !== undefined && typeof params.task !== "string") {
 			return { ok: false, error: "Structured single-child task must be a string when provided.", mode: "workflow" };
 		}
+		// A task without an agent is left for Jev subagent routing; the executor rejects it when routing cannot choose.
+		const agentless = params.agent === undefined && typeof params.task === "string" && params.task.trim() !== "";
+		if (!agentless && (typeof params.agent !== "string" || !params.agent.trim())) {
+			return { ok: false, error: "Structured single-child execution requires agent to be a non-empty string.", mode: "workflow" };
+		}
 		return {
 			ok: true,
 			params: {
 				...params,
-				agent: params.agent.trim(),
+				...(typeof params.agent === "string" ? { agent: params.agent.trim() } : {}),
 				output: params.output === undefined ? true : params.output,
 			} as T,
 		};

package/dist/extensions/pi-subagents/src/extension/schemas.ts

@@ -281,7 +281,7 @@ const ControlOverrides = Type.Object({
 
 const SubagentParamProperties = {
 	agent: Type.Optional(Type.String({ description: "Agent for one-child execution, or target for agent management actions." })),
-	task: Type.Optional(Type.String({ description: "Optional one-child task. Requires agent; cannot combine with action, workflowScript, or workflowScriptPath." })),
+	task: Type.Optional(Type.String({ description: "Optional one-child task. Requires agent unless Jev subagent routing is enabled, in which case agent may be omitted to let Jev choose by function; cannot combine with action, workflowScript, or workflowScriptPath." })),
 	extensionBindings: Type.Optional(Type.Unsafe({ type: "object", maxProperties: 16, additionalProperties: true, description: "Namespaced, bounded plain-JSON metadata delivered only to the child runtime. Namespace keys use package.name/1 syntax." })),
 	// Management action (when present, tool operates in management mode)
 	action: Type.Optional(Type.String({ minLength: 1,

package/dist/extensions/pi-subagents/src/runs/foreground/subagent-executor.ts

@@ -66,6 +66,7 @@ import { retainLiveForegroundNestedRoute } from "../../integrations/pi-web-sessi
 import { validateToolBudgetConfig } from "../shared/tool-budget.ts";
 import { usageBudgetExceededMessage, usageBudgetState, validateUsageBudgetConfig } from "../shared/usage-budget.ts";
 import { intersectSubagentCapabilityCeilings, resolveCurrentSubagentCapabilityCeiling, type ResolvedSubagentCapabilityCeiling } from "../shared/capability-ceiling.ts";
+import { describeSubagentRouting, emitSubagentRoutingTelemetry, readSubagentRoutingSettings, routeSubagentLaunch, warnJevUnavailableOnce } from "../shared/jev-subagent-routing.ts";
 import { isAgentContract } from "../shared/agent-contract.ts";
 import { normalizeExtensionBindings, type ExtensionBindings } from "../shared/extension-bindings.ts";
 import { finalizeSingleOutput, injectSingleOutputInstruction, normalizeSingleOutputOverride, outputPathMappingFromTask, resolveSingleOutputPath, validateFileOnlyOutputMode } from "../shared/single-output.ts";
@@ -6637,11 +6638,35 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 		if (cwdError) return buildRequestedModeError(effectiveParams, cwdError);
 		const parentSessionFile = ctx.sessionManager.getSessionFile() ?? null;
 		const discovered = deps.discoverAgents(effectiveCwd, scope, requestParentModel?.provider);
-		const discoveredAgents = discovered.agents;
+		let discoveredAgents = discovered.agents;
 		const unknownAgentDiagnosticContext = diagnosticContextFromDiscovery(discovered, effectiveCwd, scope);
 		const canonicalParams = canonicalizeExecutionParams(effectiveParams, discoveredAgents, discovered.agentDiagnostics, unknownAgentDiagnosticContext);
 		if (canonicalParams.error) return buildRequestedModeError(effectiveParams, canonicalParams.error);
 		effectiveParams = canonicalParams.params!;
+		// Jev fills in what a public single-child call left open (agent, tools, model tier); opt-in.
+		const routedSingle = publicExecution && !effectiveParams.chain?.length && !effectiveParams.tasks?.length && typeof effectiveParams.task === "string" && effectiveParams.task.trim() !== "";
+		const jevRouting = routedSingle ? readSubagentRoutingSettings() : undefined;
+		if (jevRouting) {
+			const routed = await routeSubagentLaunch({
+				task: effectiveParams.task!,
+				agent: effectiveParams.agent,
+				model: effectiveParams.model,
+				agents: discoveredAgents,
+				ceiling: intersectSubagentCapabilityCeilings(effectiveParams.capabilityCeiling, resolveCurrentSubagentCapabilityCeiling(resolveCurrentSessionId(ctx.sessionManager))),
+			// pi-subagents' ModelRegistry typings predate `complete`; the host registry has it, and a missing one is an abstention.
+			}, ctx as unknown as Parameters<typeof routeSubagentLaunch>[1], jevRouting);
+			emitSubagentRoutingTelemetry(deps.pi.events, routed);
+			if (routed.abstained === "no-credential" && ctx.hasUI) warnJevUnavailableOnce(ctx.ui, jevRouting.connection.provider);
+			discoveredAgents = routed.agents;
+			if (routed.agent !== undefined) effectiveParams = { ...effectiveParams, agent: routed.agent };
+			const summary = describeSubagentRouting(routed, jevRouting.tiers);
+			if (summary && ctx.hasUI) ctx.ui.notify(summary, "info");
+		}
+		if (routedSingle && !effectiveParams.agent) {
+			return buildRequestedModeError(effectiveParams, jevRouting
+				? "Jev could not choose an agent for this task. Name one: call subagent with { action: \"list\", capabilities: true } to see them."
+				: "Structured single-child execution requires agent; Jev subagent routing (jevAdvisory.routes.subagent.enabled) is off. Name an agent.");
+		}
 		if (effectiveParams.worktree === undefined && deps.config.worktree !== undefined) {
 			effectiveParams = { ...effectiveParams, worktree: deps.config.worktree };
 		}