@selesai/code 0.13.34 → 0.13.35

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to `@selesai/code` will be documented in this file.
 
+## [0.13.35] - 2026-09-29
+
+### Added
+- **`jev_find` finds files by what they do.** ripgrep gathers up to 48 candidate files (matching `pattern`, or listed under `path`/`glob` and ranked by question words), Jev judges each file's best-matching lines against a plain-words `question` in parallel batches of 16, and the agent gets ranked `path:lines (relevance)` pointers instead of file contents. It respects `.gitignore`, stays inside the working directory, skips secret-named files, and returns the unranked candidates when Jev is unavailable. It ships with `ask_jev` under `jevAdvisory.routes.ask`, stays active under the capability gateway, and leaves the loadout while Jev has no credential.
+- **Jev can set up a subagent launch (opt-in).** With `jevAdvisory.routes.subagent.enabled`, Jev fills only what the parent left open on a single-child `subagent` call: it picks an agent by function when `agent` is omitted or generic (`genericAgents`, default `["delegate"]`), may drop tools from that agent's declared list (never `read` or supervision tools), and picks a `simple`/`complex`/`reasoning` model from `tiers` when no `model` was passed. Any abstention launches exactly what was asked.
+
+### Changed
+- **The agent reaches for Jev when locating code.** The `jev_find` guidance tells the agent to use it before grep, find, or reading candidate files when it searches by behavior rather than an exact identifier; exact-name lookups still go to grep.
+
 ## [0.13.34] - 2026-09-29
 
 ### Added

package/dist/extensions/capability-gateway/index.ts

@@ -73,9 +73,10 @@ export const GATEWAY_TOOLS = new Set(["capability_catalog", "capability_discover
 
 // Graft supplies pre-turn hybrid context and must remain callable for precise
 // follow-ups; making it dormant defeats both paths. `ask_jev` is the agent's own
-// decision surface for Jev, so it is never something the agent must discover.
+// decision surface for Jev (and `jev_find` its file finder), so neither is something the agent must discover.
 const ALWAYS_ACTIVE_EXTENSION_TOOLS = new Set([
 	"ask_jev",
+	"jev_find",
 	"graft_check_freshness",
 	"graft_file_api",
 	"graft_find_all",

package/dist/extensions/jev/decisions.ts

@@ -28,7 +28,7 @@ import type { AssistantMessage, Context, Model } from "@earendil-works/pi-ai";
 // Advisory configuration (one opt-in area, per-route enablement)
 // ---------------------------------------------------------------------------
 
-export const JEV_ROUTE_NAMES = ["memory", "recommendations", "ask"] as const;
+export const JEV_ROUTE_NAMES = ["memory", "recommendations", "ask", "subagent"] as const;
 export type JevRouteName = (typeof JEV_ROUTE_NAMES)[number];
 
 export interface JevRouteConfig {
@@ -83,6 +83,17 @@ export const DEFAULT_JEV_ASK_ROUTE_CONFIG: JevRouteConfig = {
 	payloadBytes: 32 * 1024,
 };
 
+/**
+ * The `subagent` route sets up a public single-child launch (agent, tools, model tier; see
+ * pi-subagents' jev-subagent-routing.ts). Opt-in, and it sits on the launch path, so its
+ * deadline is shorter than the ask route's; its state is the task plus agent descriptions.
+ */
+export const DEFAULT_JEV_SUBAGENT_ROUTE_CONFIG: JevRouteConfig = {
+	...DEFAULT_JEV_ROUTE_CONFIG,
+	timeoutMs: 5_000,
+	payloadBytes: 16 * 1024,
+};
+
 export const DEFAULT_JEV_ADVISORY_CONFIG: JevAdvisoryConfig = {
 	provider: "tokenin",
 	model: "jev-1.13",
@@ -90,6 +101,7 @@ export const DEFAULT_JEV_ADVISORY_CONFIG: JevAdvisoryConfig = {
 		memory: { ...DEFAULT_JEV_ROUTE_CONFIG },
 		recommendations: { ...DEFAULT_JEV_ROUTE_CONFIG },
 		ask: { ...DEFAULT_JEV_ASK_ROUTE_CONFIG },
+		subagent: { ...DEFAULT_JEV_SUBAGENT_ROUTE_CONFIG },
 	},
 };
 
@@ -153,6 +165,7 @@ export function readJevAdvisoryConfig(settingsPath: string): JevAdvisoryConfig {
 			memory: routeOr(routes.memory),
 			recommendations: routeOr(routes.recommendations),
 			ask: routeOr(routes.ask, DEFAULT_JEV_ASK_ROUTE_CONFIG),
+			subagent: routeOr(routes.subagent, DEFAULT_JEV_SUBAGENT_ROUTE_CONFIG),
 		},
 	};
 }

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

@@ -19,6 +19,8 @@ const state = vi.hoisted(() => ({
 
 vi.mock("@selesai/code", () => ({
 	getSettingsPath: () => state.settingsPath,
+	// jev_find runs the real ripgrep on PATH against the temp repo.
+	ensureTool: async () => "rg",
 	// The same local shell backend the bash tool uses, scripted per command.
 	createLocalBashOperations: () => ({
 		exec: async (command: string, _cwd: string, options: { onData: (data: Buffer) => void }) => {
@@ -30,8 +32,8 @@ vi.mock("@selesai/code", () => ({
 	}),
 }));
 
-import jevAskToolExtension, { askPath, MAX_ASK_QUESTIONS } from "./jev-ask-tool.ts";
-import { JEV_ROUTING_EVENT } from "./jev/decisions.ts";
+import jevAskToolExtension, { askPath, FIND_BATCH, fitFindPayload, MAX_ASK_QUESTIONS } from "./jev-ask-tool.ts";
+import { JEV_ROUTING_EVENT, serializeJevRequest } from "./jev/decisions.ts";
 import { jevResponse, providerTemplate } from "./jev/test-support.ts";
 
 const FILE_SENTINEL = "FILE_BODY_MUST_RETURN_TO_JE ONLY";
@@ -89,6 +91,9 @@ interface AskHarness {
 	ask(params: Record<string, unknown>, signal?: AbortSignal): Promise<{ text: string; details: Record<string, unknown> }>;
 	/** The decision request Jev was sent, parsed. */
 	sent(): Record<string, unknown> | undefined;
+	/** Every tool the extension registered, by name. */
+	tools: Record<string, ToolDefinition>;
+	ctx: unknown;
 }
 
 function harness(
@@ -114,10 +119,10 @@ function harness(
 	const hooks: Record<string, (event: unknown, ctx: unknown) => unknown> = {};
 	let credential = options.credential !== false;
 	const complete = vi.fn(async () => jevResponse(answerText({})));
-	let registered: ToolDefinition | undefined;
+	const tools: Record<string, ToolDefinition> = {};
 	jevAskToolExtension({
 		registerTool: (definition: ToolDefinition) => {
-			registered = definition;
+			tools[definition.name] = definition;
 		},
 		on: (event: string, handler: (event: unknown, ctx: unknown) => unknown) => {
 			hooks[event] = handler;
@@ -143,9 +148,11 @@ function harness(
 			complete,
 		},
 	};
-	const tool = registered as ToolDefinition;
+	const tool = tools.ask_jev as ToolDefinition;
 	return {
 		tool,
+		tools,
+		ctx,
 		complete,
 		telemetry,
 		notices,
@@ -412,6 +419,64 @@ describe("missing material", () => {
 	});
 });
 
+describe("jev_find", () => {
+	const find = async (session: AskHarness, params: Record<string, unknown>) => {
+		const result = await session.tools.jev_find.execute("call-f", params, undefined, undefined, session.ctx);
+		return { text: result.content[0]?.text ?? "", details: result.details };
+	};
+
+	beforeAll(() => {
+		writeFileSync(join(repo, "src", "other.ts"), "// mentions round only in passing\nexport const x = 1;\n", "utf-8");
+		writeFileSync(join(repo, ".env"), "round=SECRET_ENV_VALUE\n", "utf-8");
+	});
+
+	it("ranks ripgrep's candidates by Jev relevance and returns pointers, never contents", async () => {
+		const session = harness();
+		// Jev: the file whose question names round.ts is relevant, the rest are not.
+		session.complete.mockImplementation(async (_model: unknown, request: { messages: Array<{ content: string }> }) => {
+			const sent = JSON.parse(request.messages[0].content) as { questions: Record<string, { instructions: { question: string } }> };
+			const answers = Object.fromEntries(
+				Object.entries(sent.questions).map(([name, q]) => [name, { noul: q.instructions.question.includes("round.ts") ? 0.93 : 0.08 }]),
+			);
+			return jevResponse(answerText(answers));
+		});
+		const result = await find(session, { question: "where is rounding implemented", pattern: "round", ignoreCase: true });
+
+		expect(result.text).toMatch(/judged 2 of 2 candidate/);
+		expect(result.text).toContain("- src/round.ts:1 (0.93)");
+		expect(result.text).not.toContain("other.ts");
+		expect(result.text).not.toContain(FILE_SENTINEL);
+		const sent = session.sent() as { state: { files: Record<string, string> } };
+		expect(Object.keys(sent.state.files).sort()).toEqual(["src/other.ts", "src/round.ts"]);
+		expect(sent.state.files["src/round.ts"]).toContain(FILE_SENTINEL);
+		expect(JSON.stringify(sent)).not.toContain("SECRET_ENV_VALUE");
+	});
+
+	it("lists a directory by glob and still returns candidates when Jev is unreachable", async () => {
+		const session = harness({ credential: false });
+		const result = await find(session, { question: "rounding", path: "src", glob: "*.ts" });
+
+		expect(session.complete).not.toHaveBeenCalled();
+		expect(result.text).toMatch(/Jev did not judge \(no-credential\); 2 candidate/);
+		// The question word in the path orders the unjudged listing.
+		expect(result.text.split("\n")[1]).toBe("- src/round.ts");
+	});
+
+	it("shrinks escape-heavy snippets until a full batch fits the request budget", () => {
+		// Quotes and newlines double under JSON escaping, which is what overflowed live.
+		const snippet = '"\n\t\\'.repeat(1_000);
+		const batch = Array.from({ length: FIND_BATCH }, (_, i) => ({ path: `src/f${i}.ts`, lines: [], snippet }));
+		const payload = fitFindPayload("q", batch, 32 * 1024);
+		expect(serializeJevRequest(payload, 32 * 1024)).toBeDefined();
+		expect(Object.keys(payload.questions as object)).toHaveLength(FIND_BATCH);
+	});
+
+	it("refuses a search root outside the working directory", async () => {
+		const result = await find(harness(), { question: "x", path: ".." });
+		expect(result.text).toContain("outside the working directory");
+	});
+});
+
 describe("askPath symlinks", () => {
 	it("refuses links that escape the working directory or point at a secret", () => {
 		const root = mkdtempSync(join(tmpdir(), "ask-path-"));

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 };
 		}

package/dist/extensions/pi-subagents/src/runs/shared/jev-subagent-routing.ts

@@ -0,0 +1,255 @@
+/**
+ * Jev-assisted setup for a public single-child launch. Opt-in:
+ * `jevAdvisory.routes.subagent.enabled: true` in the agent settings.json.
+ *
+ * Jev only fills what the parent left open, and every answer can only narrow:
+ * 1. Agent: chosen by function when `agent` is omitted or generic (default "delegate"),
+ *    from native, enabled agents the capability ceiling allows.
+ * 2. Tools: Jev may drop tools from the agent's declared allowlist for this task; it never adds one.
+ * 3. Model tier: simple | complex | reasoning, mapped through the user's
+ *    `jevAdvisory.routes.subagent.tiers` (provider/id values), only when the parent passed no `model`.
+ *
+ * Every failure (no credential, timeout, malformed or low-confidence answer) leaves the launch
+ * exactly as requested. Launch validation, ceilings, and preflight remain authoritative.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { AgentConfig } from "../../agents/agents.ts";
+import { getAgentDir } from "../../shared/utils.ts";
+import { isAgentAllowedByCapabilityCeiling, type ResolvedSubagentCapabilityCeiling } from "./capability-ceiling.ts";
+import {
+	askJev,
+	buildConversation,
+	buildJevPayload,
+	emitJevTelemetry,
+	jevConnection,
+	readJevAdvisoryConfig,
+	type JevAbstainReason,
+	type JevConnection,
+	type JevQuestion,
+	type JevRuntime,
+} from "../../../../jev/decisions.ts";
+
+export { warnJevUnavailableOnce } from "../../../../jev/decisions.ts";
+
+export const MODEL_TIERS = ["simple", "complex", "reasoning"] as const;
+export type ModelTier = (typeof MODEL_TIERS)[number];
+
+const KEEP = "keep";
+const DEFAULT_GENERIC_AGENTS = ["delegate"];
+/** Never offered for removal: skills load through read, and the rest are supervision plumbing. */
+const PROTECTED_TOOLS = new Set(["read", "contact_supervisor", "intercom", "structured_output", "subagent", "subagent_supervisor"]);
+// ponytail: tools past this cap are simply kept; raise it if agents declare long allowlists.
+const MAX_TOOL_QUESTIONS = 10;
+const DESCRIPTION_CHARS = 300;
+
+const TIER_CRITERIA: Record<ModelTier, string> = {
+	simple: "Mechanical or lookup work: find, list, summarize, rename, run a command and report.",
+	complex: "Multi-step implementation or investigation across several files with ordinary judgment.",
+	reasoning: "Hard judgment: subtle debugging, architecture or security review, tricky algorithms, ambiguous trade-offs.",
+};
+
+export interface SubagentRoutingSettings {
+	connection: JevConnection;
+	maxBytes: number;
+	contextChars: number;
+	genericAgents: string[];
+	tiers: Partial<Record<ModelTier, string>>;
+}
+
+export interface SubagentRoutingInput {
+	task: string;
+	agent?: string;
+	model?: string;
+	agents: AgentConfig[];
+	ceiling?: ResolvedSubagentCapabilityCeiling;
+}
+
+export interface SubagentRoutingResult {
+	/** The agent to launch: Jev's pick, or the requested one. */
+	agent?: string;
+	/** The run's agent list, with the launched agent narrowed (tools) or re-modelled (tier). */
+	agents: AgentConfig[];
+	routedAgent?: string;
+	tier?: ModelTier;
+	droppedTools: string[];
+	/** First reason a question went unanswered, for telemetry and the missing-agent error. */
+	abstained?: JevAbstainReason;
+	elapsedMs: number;
+	questions: number;
+}
+
+type JevAsk = typeof askJev;
+
+/** The route's settings, or undefined while it is off. Never throws. */
+export function readSubagentRoutingSettings(settingsPath = path.join(getAgentDir(), "settings.json")): SubagentRoutingSettings | undefined {
+	const config = readJevAdvisoryConfig(settingsPath);
+	const route = config.routes.subagent;
+	if (!route.enabled) return undefined;
+	let raw: Record<string, unknown> = {};
+	try {
+		const parsed = JSON.parse(fs.readFileSync(settingsPath, "utf-8")) as { jevAdvisory?: { routes?: { subagent?: Record<string, unknown> } } };
+		raw = parsed?.jevAdvisory?.routes?.subagent ?? {};
+	} catch {
+		// readJevAdvisoryConfig already defaulted; extra fields just stay unset.
+	}
+	const tiers: Partial<Record<ModelTier, string>> = {};
+	const rawTiers = raw.tiers && typeof raw.tiers === "object" ? (raw.tiers as Record<string, unknown>) : {};
+	for (const tier of MODEL_TIERS) {
+		const model = rawTiers[tier];
+		if (typeof model === "string" && model.trim()) tiers[tier] = model.trim();
+	}
+	const generic = Array.isArray(raw.genericAgents) ? raw.genericAgents.filter((name): name is string => typeof name === "string" && name.trim() !== "") : DEFAULT_GENERIC_AGENTS;
+	return {
+		connection: jevConnection(config, route),
+		maxBytes: route.payloadBytes,
+		contextChars: route.contextChars,
+		genericAgents: generic,
+		tiers,
+	};
+}
+
+/** Agents Jev may pick: native, enabled, file-defined, and inside the capability ceiling. */
+export function routableAgents(agents: readonly AgentConfig[], ceiling: ResolvedSubagentCapabilityCeiling | undefined): AgentConfig[] {
+	return agents.filter(
+		(agent) =>
+			agent.source !== "runtime"
+			&& agent.disabled !== true
+			&& agent.runner?.type !== "external-cli"
+			&& agent.runner?.type !== "external-job"
+			&& isAgentAllowedByCapabilityCeiling(agent.name, ceiling),
+	);
+}
+
+function droppableTools(agent: AgentConfig): string[] {
+	const excluded = new Set(agent.excludeTools ?? []);
+	return (agent.tools ?? [])
+		.filter((tool) => !PROTECTED_TOOLS.has(tool) && !excluded.has(tool) && !/[/\\]|\.(?:ts|js)$/.test(tool))
+		.slice(0, MAX_TOOL_QUESTIONS);
+}
+
+function toolKey(index: number): string {
+	return `tool_${index}`;
+}
+
+export async function routeSubagentLaunch(
+	input: SubagentRoutingInput,
+	ctx: JevRuntime,
+	settings: SubagentRoutingSettings,
+	ask: JevAsk = askJev,
+): Promise<SubagentRoutingResult> {
+	const result: SubagentRoutingResult = { agent: input.agent, agents: input.agents, droppedTools: [], elapsedMs: 0, questions: 0 };
+	const conversation = buildConversation(input.task.slice(0, settings.contextChars), [], { contextTurns: 1, contextChars: settings.contextChars });
+	const noteAbstain = (reason: JevAbstainReason | undefined) => {
+		if (reason && !result.abstained) result.abstained = reason;
+	};
+
+	// 1. Agent by function, only when the parent left it open.
+	const generic = input.agent !== undefined && settings.genericAgents.includes(input.agent);
+	if (input.agent === undefined || generic) {
+		const candidates = routableAgents(input.agents, input.ceiling).filter((agent) => agent.name !== input.agent);
+		if (candidates.length > 0) {
+			const criteria: Record<string, string> = {};
+			if (generic) criteria[KEEP] = `Keep the generic "${input.agent}" agent: no listed specialist fits this task better.`;
+			for (const agent of candidates) criteria[agent.name] = agent.description.slice(0, DESCRIPTION_CHARS);
+			const questions: Record<string, JevQuestion> = {
+				agent: {
+					question: "Which subagent's specialization best fits this delegated task?",
+					focus: "Judge by what the task needs done (read-only review, research, investigation, implementation), not by wording that names an agent.",
+					criteria,
+				},
+			};
+			const decision = await ask(ctx, settings.connection, {
+				payload: buildJevPayload(conversation, questions),
+				maxBytes: settings.maxBytes,
+				allowed: { agent: Object.keys(criteria) },
+			});
+			result.elapsedMs += decision.elapsedMs;
+			result.questions += 1;
+			const pick = decision.choices.agent?.choice;
+			if (pick && pick !== KEEP) {
+				result.agent = pick;
+				result.routedAgent = pick;
+			}
+			noteAbstain(decision.failure ?? decision.rejected.agent);
+		}
+	}
+
+	const config = result.agent === undefined ? undefined : input.agents.find((agent) => agent.name === result.agent);
+	if (!config) return result;
+
+	// 2 + 3. Tool narrowing and model tier, for the agent that will actually launch.
+	const tools = droppableTools(config);
+	const tierChoices = input.model === undefined ? MODEL_TIERS.filter((tier) => settings.tiers[tier] !== undefined) : [];
+	const questions: Record<string, JevQuestion> = {};
+	const allowed: Record<string, string[]> = {};
+	if (tierChoices.length > 1) {
+		questions.tier = {
+			question: "How demanding is this delegated task for the model that runs it?",
+			criteria: Object.fromEntries(tierChoices.map((tier) => [tier, TIER_CRITERIA[tier]])),
+		};
+		allowed.tier = [...tierChoices];
+	}
+	tools.forEach((tool, index) => {
+		questions[toolKey(index)] = {
+			question: `Does this delegated task need the "${tool}" tool?`,
+			focus: "Answer unneeded only when the task clearly cannot require it; when in doubt, it is needed.",
+			criteria: { needed: `The task may need ${tool}.`, unneeded: `The task clearly never needs ${tool}.` },
+		};
+		allowed[toolKey(index)] = ["needed", "unneeded"];
+	});
+	if (Object.keys(questions).length === 0) return result;
+
+	const decision = await ask(ctx, settings.connection, {
+		payload: buildJevPayload(conversation, questions),
+		maxBytes: settings.maxBytes,
+		allowed,
+	});
+	result.elapsedMs += decision.elapsedMs;
+	result.questions += Object.keys(questions).length;
+	noteAbstain(decision.failure);
+
+	const tier = decision.choices.tier?.choice as ModelTier | undefined;
+	const tierModel = tier ? settings.tiers[tier] : undefined;
+	if (tierModel) result.tier = tier;
+	// Dropping a tool needs a stated confidence: an unquantified "unneeded" keeps the tool.
+	result.droppedTools = tools.filter((_tool, index) => {
+		const choice = decision.choices[toolKey(index)];
+		return choice?.choice === "unneeded" && typeof choice.confidence === "number";
+	});
+	if (!tierModel && result.droppedTools.length === 0) return result;
+
+	const { modelProvider: _modelProvider, modelSource: _modelSource, ...base } = config;
+	const routed: AgentConfig = {
+		...(tierModel ? base : config),
+		...(tierModel ? { model: tierModel } : {}),
+		...(result.droppedTools.length > 0 ? { excludeTools: [...(config.excludeTools ?? []), ...result.droppedTools] } : {}),
+	};
+	result.agents = input.agents.map((agent) => (agent === config ? routed : agent));
+	return result;
+}
+
+/** Content-free: shape and outcome only, never the task, descriptions, or answers. */
+export function emitSubagentRoutingTelemetry(events: { emit(channel: string, data: unknown): void } | undefined, result: SubagentRoutingResult): void {
+	if (result.questions === 0) return;
+	const changed = Boolean(result.routedAgent || result.tier || result.droppedTools.length > 0);
+	emitJevTelemetry(events, "decision", {
+		route: "subagent",
+		outcome: changed ? "jev" : "fallback",
+		candidates: result.questions,
+		elapsedMs: result.elapsedMs,
+		...(result.routedAgent ? { agent: result.routedAgent } : {}),
+		...(result.tier ? { tier: result.tier } : {}),
+		dropped: result.droppedTools.length,
+		...(result.abstained ? { reason: result.abstained } : {}),
+	});
+}
+
+/** One line for the user and the parent: what Jev set up, or nothing when it changed nothing. */
+export function describeSubagentRouting(result: SubagentRoutingResult, tiers: Partial<Record<ModelTier, string>>): string | undefined {
+	const parts: string[] = [];
+	if (result.routedAgent) parts.push(`agent ${result.routedAgent}`);
+	if (result.tier) parts.push(`${result.tier} tier (${tiers[result.tier]})`);
+	if (result.droppedTools.length > 0) parts.push(`without ${result.droppedTools.join(", ")}`);
+	return parts.length > 0 ? `Jev set up this subagent: ${parts.join("; ")}.` : undefined;
+}

package/dist/extensions/pi-subagents/test/unit/jev-subagent-routing.test.ts

@@ -0,0 +1,117 @@
+import assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { describe, it } from "node:test";
+import type { AgentConfig } from "../../src/agents/agents.ts";
+import {
+	readSubagentRoutingSettings,
+	routeSubagentLaunch,
+	type SubagentRoutingSettings,
+} from "../../src/runs/shared/jev-subagent-routing.ts";
+
+function agent(name: string, extra: Partial<AgentConfig> = {}): AgentConfig {
+	return { name, description: `${name} agent`, systemPromptMode: "append", inheritProjectContext: true, inheritGlobalContext: true, inheritSkills: true, systemPrompt: "", source: "builtin", filePath: `${name}.md`, ...extra } as AgentConfig;
+}
+
+const agents = [
+	agent("delegate"),
+	agent("reviewer", { tools: ["read", "grep"] }),
+	agent("worker", { tools: ["read", "bash", "edit", "write"], model: "anthropic/opus", modelProvider: "anthropic" }),
+	agent("secret", { disabled: true }),
+	agent("external", { runner: { type: "external-cli" } as AgentConfig["runner"] }),
+];
+
+const settings: SubagentRoutingSettings = {
+	connection: { provider: "tokenin", model: "jev", timeoutMs: 1000, minConfidence: 0.6 },
+	maxBytes: 16_384,
+	contextChars: 4000,
+	genericAgents: ["delegate"],
+	tiers: { simple: "p/small", reasoning: "p/big" },
+};
+
+type Asked = { allowed: Record<string, readonly string[]> };
+/** A fake Jev: answers each asked question from `answers`, records what was offered. */
+function fakeAsk(answers: Record<string, { choice: string; confidence?: number }>, asked: Asked[] = []) {
+	return async (_ctx: unknown, _connection: unknown, request: Asked) => {
+		asked.push({ allowed: request.allowed });
+		const choices = Object.fromEntries(Object.keys(request.allowed).filter((q) => answers[q]).map((q) => [q, answers[q]!]));
+		return { choices, rejected: {}, elapsedMs: 5 };
+	};
+}
+const ctx = {} as never;
+
+describe("Jev subagent routing", () => {
+	it("routes an agentless task, offering only enabled native agents inside the ceiling", async () => {
+		const asked: Asked[] = [];
+		const result = await routeSubagentLaunch(
+			{ task: "fix the bug", agents, ceiling: { allowedAgents: ["delegate", "worker", "secret"], sources: ["test"] } as never },
+			ctx, settings, fakeAsk({ agent: { choice: "worker", confidence: 0.9 } }, asked) as never,
+		);
+		assert.equal(result.agent, "worker");
+		assert.deepEqual(asked[0]!.allowed.agent, ["delegate", "worker"]);
+	});
+
+	it("offers keep for a generic agent and never re-routes an explicit specialist", async () => {
+		const asked: Asked[] = [];
+		const kept = await routeSubagentLaunch({ task: "t", agent: "delegate", agents }, ctx, settings, fakeAsk({ agent: { choice: "keep", confidence: 0.9 } }, asked) as never);
+		assert.equal(kept.agent, "delegate");
+		assert.ok(asked[0]!.allowed.agent!.includes("keep"));
+		assert.ok(!asked[0]!.allowed.agent!.includes("delegate"));
+
+		const explicitAsked: Asked[] = [];
+		const explicit = await routeSubagentLaunch({ task: "t", agent: "reviewer", model: "x/y", agents }, ctx, settings, fakeAsk({}, explicitAsked) as never);
+		assert.equal(explicit.agent, "reviewer");
+		assert.ok(explicitAsked.every((ask) => !("agent" in ask.allowed)));
+	});
+
+	it("abstention leaves the launch as requested", async () => {
+		const result = await routeSubagentLaunch({ task: "t", agents }, ctx, settings, (async () => ({ choices: {}, rejected: { agent: "no-credential" }, failure: "no-credential", elapsedMs: 0 })) as never);
+		assert.equal(result.agent, undefined);
+		assert.equal(result.agents, agents);
+		assert.equal(result.abstained, "no-credential");
+	});
+
+	it("only drops declared, unprotected tools on a confident unneeded, and applies the tier model", async () => {
+		const asked: Asked[] = [];
+		const result = await routeSubagentLaunch(
+			{ task: "summarize the README", agent: "worker", agents },
+			ctx, settings,
+			fakeAsk({ tier: { choice: "simple", confidence: 0.8 }, tool_0: { choice: "unneeded", confidence: 0.9 }, tool_1: { choice: "unneeded" }, tool_2: { choice: "needed", confidence: 0.9 } }, asked) as never,
+		);
+		// read is never offered: tool_0..2 are bash, edit, write.
+		assert.deepEqual(Object.keys(asked[0]!.allowed).sort(), ["tier", "tool_0", "tool_1", "tool_2"]);
+		assert.deepEqual(asked[0]!.allowed.tier, ["simple", "reasoning"]);
+		assert.deepEqual(result.droppedTools, ["bash"]);
+		const worker = result.agents.find((a) => a.name === "worker")!;
+		assert.deepEqual(worker.excludeTools, ["bash"]);
+		assert.equal(worker.model, "p/small");
+		assert.equal(worker.modelProvider, undefined);
+		assert.deepEqual(worker.tools, ["read", "bash", "edit", "write"]);
+		// The discovered list itself is untouched.
+		assert.equal(agents.find((a) => a.name === "worker")!.model, "anthropic/opus");
+	});
+
+	it("skips the tier question when the parent chose a model", async () => {
+		const asked: Asked[] = [];
+		const result = await routeSubagentLaunch({ task: "t", agent: "worker", model: "x/y", agents }, ctx, settings, fakeAsk({ tier: { choice: "simple", confidence: 0.9 } }, asked) as never);
+		assert.ok(!("tier" in asked[0]!.allowed));
+		assert.equal(result.tier, undefined);
+	});
+
+	it("reads settings: off by default, tiers and generic agents when enabled", () => {
+		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "jev-subagent-"));
+		try {
+			const file = path.join(dir, "settings.json");
+			fs.writeFileSync(file, JSON.stringify({ jevAdvisory: { routes: {} } }));
+			assert.equal(readSubagentRoutingSettings(file), undefined);
+			fs.writeFileSync(file, JSON.stringify({ jevAdvisory: { routes: { subagent: { enabled: true, tiers: { simple: " p/s ", bogus: "x" }, genericAgents: ["delegate", "general"] } } } }));
+			const read = readSubagentRoutingSettings(file)!;
+			assert.deepEqual(read.tiers, { simple: "p/s" });
+			assert.deepEqual(read.genericAgents, ["delegate", "general"]);
+			assert.equal(read.connection.timeoutMs, 5000);
+		} finally {
+			fs.rmSync(dir, { recursive: true, force: true });
+		}
+	});
+});

package/dist/extensions/pi-subagents/test/unit/public-execution.test.ts

@@ -19,6 +19,8 @@ describe("public subagent execution normalization", () => {
 				output: true,
 			},
 		});
+		// Agentless tasks are left for Jev subagent routing; the executor rejects them when it cannot choose.
+		assert.deepEqual(normalizePublicSubagentExecution({ task: "work" }), { ok: true, params: { task: "work", output: true } });
 		assert.deepEqual(normalizePublicSubagentExecution({ agent: "worker" }), {
 			ok: true,
 			params: {
@@ -171,7 +173,7 @@ describe("public subagent execution normalization", () => {
 			{ action: "reject-checkpoint", id: "run" },
 			{ agent: "" },
 			{ agent: 42 },
-			{ task: "work" },
+			{ task: " " },
 			{ agent: "worker", task: 42 },
 			{ agent: "worker", workflowScript: "return 1" },
 			{ action: "status", task: "work" },

package/docs/settings.md

@@ -50,7 +50,7 @@ Use `/trust` in interactive mode to save a project trust decision for future ses
 
 The bundled `jev-advisory-routing` extension uses the Jev decisions model for bounded opt-in
 routing. The host-side routes stay off until they are enabled in `jevAdvisory`; the agent's own
-`ask` route is on by default. All three share one Jev provider/model pair:
+`ask` route is on by default. All routes share one Jev provider/model pair:
 
 - `memory` — only after an explicit durable-memory cue (for example “the convention we
   decided” or “don't repeat the past failure”), Jev chooses one read-only local
@@ -67,6 +67,21 @@ routing. The host-side routes stay off until they are enabled in `jevAdvisory`;
   of the agent's loadout before each run (it returns after `/tokenin add`, no reload needed), and a call
   that slips through reads no file and runs no command.
 
+  The same route also offers `jev_find`, a file finder: ripgrep gathers up to 48 candidate files
+  (those matching `pattern`, or every file under `path` filtered by `glob`, ranked by question words),
+  Jev judges each file's best-matching lines against the agent's `question` in parallel batches of 16,
+  and the agent gets ranked `path:lines (relevance)` pointers — never file contents. It respects
+  `.gitignore`, stays inside the working directory, skips secret-named files, and still returns the
+  unranked candidates when Jev is unavailable.
+- `subagent` — sets up a single-child `subagent` call from the parent agent (off by default). Jev only
+  fills what the parent left open, and can only narrow: (1) when `agent` is omitted or generic
+  (`genericAgents`, default `["delegate"]`), it picks an agent by function from enabled native agents
+  inside the capability ceiling; (2) it may drop tools from that agent's declared `tools` for this run
+  (never `read` or supervision tools, and never adds one); (3) when `tiers` is set and the parent
+  passed no `model`, it picks `simple`, `complex`, or `reasoning` and launches that tier's model. Jev
+  sees only the task and agent descriptions. Any abstention launches exactly what was asked; an
+  agentless task that Jev cannot route is rejected with a request to name an agent.
+
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
 | `jevAdvisory.provider` | string | `"tokenin"` | Provider serving the Jev decisions deployment |
@@ -74,12 +89,15 @@ routing. The host-side routes stay off until they are enabled in `jevAdvisory`;
 | `jevAdvisory.baseUrl` | string | inherited | Base URL override; defaults to any registered model of `provider` |
 | `jevAdvisory.routes.memory.enabled` | boolean | `false` | Enable the memory-lookup route |
 | `jevAdvisory.routes.recommendations.enabled` | boolean | `false` | Enable skill/workflow and verification recommendations |
-| `jevAdvisory.routes.ask.enabled` | boolean | `true` | Offer the agent the `ask_jev` tool; set `false` to turn it off |
-| `<route>.timeoutMs` | number | `8000` | Route request timeout (ms); memory is capped at 750ms; `ask` defaults to `15000` |
+| `jevAdvisory.routes.ask.enabled` | boolean | `true` | Offer the agent the `ask_jev` and `jev_find` tools; set `false` to turn both off |
+| `jevAdvisory.routes.subagent.enabled` | boolean | `false` | Let Jev choose the agent, tools, and model tier of a subagent call |
+| `jevAdvisory.routes.subagent.tiers` | object | unset | `{ "simple"?, "complex"?, "reasoning"? }` → `provider/id` model; tier routing needs at least two |
+| `jevAdvisory.routes.subagent.genericAgents` | string[] | `["delegate"]` | Agents Jev may replace with a specialist |
+| `<route>.timeoutMs` | number | `8000` | Route request timeout (ms); memory is capped at 750ms; `ask` defaults to `15000`, `subagent` to `5000` |
 | `<route>.minConfidence` | number | `0.6` | Below this Jev confidence the route abstains |
 | `<route>.contextTurns` | number | `4` | Prior user turns sent as recommendation context; memory sends only the current bounded prompt |
 | `<route>.contextChars` | number | `4000` | Character budget for recommendation context |
-| `<route>.payloadBytes` | number | `8192` | Hard cap on the serialized decision request; `ask` defaults to `32768` |
+| `<route>.payloadBytes` | number | `8192` | Hard cap on the serialized decision request; `ask` defaults to `32768`, `subagent` to `16384` |
 
 `ask` ignores `minConfidence`, `contextTurns`, and `contextChars`: it returns every confidence to the
 agent, and its context is whatever the agent put in the request.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@selesai/code",
-  "version": "0.13.34",
+  "version": "0.13.35",
   "description": "Maintained, extension-first Pi coding agent with built-in workflows, subagents, web research, questions, skills, and an enhanced terminal UI.",
   "type": "module",
   "engines": {