@selesai/code 0.13.32 → 0.13.34

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to `@selesai/code` will be documented in this file.
 
+## [0.13.34] - 2026-09-29
+
+### Added
+- **`ask_jev` lets the agent ask Jev typed questions.** One bounded call over the agent's own prose, up to eight file paths, and one command returns choice, score, or noul answers with confidences; file contents and command output are sent to Jev but never returned to the agent. On by default through `jevAdvisory.routes.ask`; without Token-In credentials the tool leaves the loadout until `/tokenin add`, and nothing is read or run.
+- **`capability_discover({ job })` lets Jev pick the capability.** The agent describes what it is about to do and Jev answers which tool and which skill fit, each possibly `none`. It has its own timeout (`discoverTimeoutMs`, 5 s, capped at 15 s), and the option is left out of the instructions while Jev has no credential.
+- **pi-hermes-memory reads its options from `settings.json`.** The `hermesMemory` object in the global settings takes precedence over the legacy `hermes-memory-config.json`, and consolidation shows progress in the status line.
+
+### Fixed
+- **`ask_jev` paths are checked after resolving symlinks.** A symlink inside the working directory can no longer expose a file outside it, or a secret file under an innocent name.
+- **Agents check capabilities before saying a tool is unavailable.** The capability instruction tells the agent to activate a named tool through `capability_discover` first, and an intercom message received while `intercom` is inactive says how to activate it.
+- **Live tokens-per-second no longer reads ~1 token on Anthropic streams.** The live count takes the larger of the official and estimated counts, because the official count is only final at `message_delta`.
+
+## [0.13.33] - 2026-09-26
+
+### Added
+- **Subagent cost is exposed through extension RPC.** `cost` joins the versioned `subagents:rpc:v1` method list and returns the same parent-plus-child accounting `/subagent-cost` renders; `ping` advertises the report version. It is read-only, but it walks the current session branch and existing run artifacts, so callers should request it on turn boundaries rather than on a timer.
+- **Async workflow status reports terminal proof.** `subagent({ action: "status" })` details now include `workflowTerminalProof`, the shared child-exit evidence for workflow runs.
+- **Native children can use the scoped capability gateway.** A child launch loads the gateway when extension policy permits it, exposing `capability_catalog`, `capability_discover`, and `capability_skill_show` for tools in that child's effective registry. The gateway never installs or provides a missing tool provider, and `SELESAI_CAPABILITY_GATEWAY=0` still disables it.
+
+### Changed
+- **The packaged `worker` agent starts from fresh context.** `worker` now declares `defaultContext: fresh` and `acceptanceRole: writer`; an explicit `context: "fork"` still wins.
+
+### Fixed
+- **Capability gateway controls no longer count as mutation capability.** A read-only child that receives `capability_catalog`, `capability_discover`, and `capability_skill_show` is still rejected for an implementation task with no mutation-capable tools, so the gateway does not disarm the implementation guard.
+- **Structured output rejections keep their evidence.** Foreground and background runs now report the bounded rejection diagnostic — schema and validator failures summarized, submitted values redacted — instead of a generic missing-call error, and background results mark `structuredOutputFailed`.
+- **`subagent_supervisor` requires fanout authorization.** A child that declares the supervisor reply tool without `subagent` in its effective tools allowlist (or `allowNestedSubagents`) now fails the launch instead of silently receiving the tool.
+- **Git routing environment is stripped from child processes.** Background runners and external CLI default launches no longer inherit `GIT_DIR`, `GIT_WORK_TREE`, `GIT_INDEX_FILE`, and Git's other local environment variables, so a child's Git commands stay in its own working directory.
+
 ## [0.13.32] - 2026-09-24
 
 ### Fixed

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

@@ -52,8 +52,11 @@ export function buildToolCatalog(tools: ToolInfo[], gatewayToolNames: Set<string
 }
 
 export function buildSkillCatalog(skills: ResolvedSkillInfo[]): CatalogEntry[] {
+	// The same skill resolves once per source (user dir, package, project); the first one wins, as it
+	// does for loading. Duplicates would only spend a bounded Jev request twice on one name.
+	const seen = new Set<string>();
 	return skills
-		.filter((skill) => !skill.disableModelInvocation)
+		.filter((skill) => !skill.disableModelInvocation && !seen.has(skill.name) && seen.add(skill.name))
 		.map((skill) => ({
 			name: skill.name,
 			kind: "skill" as const,

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

@@ -12,6 +12,7 @@ import {
 	toolSummary,
 	type CatalogEntry,
 } from "./catalog.ts";
+import { capabilityInstruction, describePick, invocationContract, schemaShape } from "./index.ts";
 
 const tool = (overrides: Partial<ToolInfo>): ToolInfo =>
 	({
@@ -67,6 +68,16 @@ describe("catalog metadata", () => {
 		expect(entries[0]!.kind).toBe("skill");
 	});
 
+	it("lists a skill resolved from several sources once, keeping the first", () => {
+		const entries = buildSkillCatalog([
+			skill({ name: "to-prd", description: "Turn the conversation into a PRD.", category: "docs" }),
+			skill({ name: "research" }),
+			skill({ name: "to-prd", description: "Older copy." }),
+		]);
+		expect(entries.map((e) => e.name)).toEqual(["to-prd", "research"]);
+		expect(entries[0]!.category).toBe("docs");
+	});
+
 	it("falls back to the file frontmatter description when the resolved description is empty", () => {
 		const dir = mkdtempSync(join(tmpdir(), "gw-skill-"));
 		const filePath = join(dir, "SKILL.md");
@@ -85,9 +96,9 @@ describe("catalog metadata", () => {
 
 describe("deterministic routing", () => {
 	const catalog: CatalogEntry[] = [
-		{ name: "grep_app_search", kind: "tool", summary: "Search public GitHub code", aliases: ["github-search"], category: "web" },
-		{ name: "grep_app_fetch", kind: "tool", summary: "Fetch a public GitHub file", aliases: [], category: "web" },
-		{ name: "research", kind: "skill", summary: "Investigate a question against primary sources", aliases: [], category: "research" },
+		{ name: "grep_app_search", kind: "tool", summary: "Search public GitHub code", aliases: ["github-search"], category: "web", eligible: true },
+		{ name: "grep_app_fetch", kind: "tool", summary: "Fetch a public GitHub file", aliases: [], category: "web", eligible: true },
+		{ name: "research", kind: "skill", summary: "Investigate a question against primary sources", aliases: [], category: "research", eligible: true },
 	];
 
 	it("auto-activates a unique high-confidence tool match", () => {
@@ -105,7 +116,7 @@ describe("deterministic routing", () => {
 	it("auto-activates a uniquely identifiable one-character tool typo", () => {
 		const result = route("activate inercom", [
 			...catalog,
-			{ name: "intercom", kind: "tool", summary: "Coordinate with other local sessions", aliases: [], category: "coordination" },
+			{ name: "intercom", kind: "tool", summary: "Coordinate with other local sessions", aliases: [], category: "coordination", eligible: true },
 		]);
 		expect(result.action).toBe("activate");
 		expect(result.entry?.name).toBe("intercom");
@@ -135,3 +146,81 @@ describe("deterministic routing", () => {
 		expect(a).toEqual(b);
 	});
 });
+
+describe("invocation contract", () => {
+	const toolWith = (parameters: unknown, overrides: Partial<ToolInfo> = {}) =>
+		tool({ name: "graft_find_code", description: "Find code by question.", parameters: parameters as never, ...overrides });
+
+	it("lists each parameter with its shape and required flag", () => {
+		const contract = invocationContract(
+			toolWith({
+				type: "object",
+				properties: {
+					question: { type: "string", description: "What you want to understand, in plain words." },
+					limit: { type: "number" },
+				},
+				required: ["question"],
+			}),
+		);
+		expect(contract).toContain("graft_find_code — Find code by question.");
+		expect(contract).toContain("- question (string, required): What you want to understand, in plain words.");
+		expect(contract).toContain("- limit (number, optional)");
+	});
+
+	it("names nested shapes instead of expanding them", () => {
+		expect(schemaShape({ type: "array", items: { type: "object" } })).toBe("array<object>");
+		expect(schemaShape({ anyOf: [{ type: "string" }, { type: "number" }] })).toBe("one of several");
+		expect(schemaShape({ enum: ["a", "b"] })).toBe('"a" | "b"');
+		expect(schemaShape({})).toBe("value");
+	});
+
+	it("says so when a tool takes no parameters", () => {
+		expect(invocationContract(toolWith({ type: "object", properties: {} }))).toContain("Parameters: none");
+	});
+
+	it("clips long text and never carries the schema itself", () => {
+		const contract = invocationContract(
+			toolWith({
+				type: "object",
+				properties: { question: { type: "string", description: "x".repeat(500) } },
+				required: ["question"],
+			}),
+		);
+		expect(contract).toContain("…");
+		expect(contract).not.toContain('"type"');
+		expect(contract.split("\n").every((line) => line.length <= 200)).toBe(true);
+	});
+});
+
+describe("capability instruction", () => {
+	it("mentions the job route only when Jev can answer it", () => {
+		expect(capabilityInstruction(true)).toContain("capability_discover with `job`");
+		const offline = capabilityInstruction(false);
+		expect(offline).not.toContain("`job`");
+		expect(offline).toContain("capability_catalog");
+		expect(offline).toContain("exact `name`");
+	});
+});
+
+describe("describePick", () => {
+	const side = (pick: Parameters<typeof describePick>[1]["pick"], offered = 3, dropped = 0) => ({ pick, offered, dropped });
+
+	it("reads a hesitant Jev as no confident pick rather than a failure", () => {
+		expect(describePick("Skill", side({ selected: false, reason: "low-confidence" }), undefined, "x")).toBe(
+			"Skill: no confident pick.",
+		);
+		expect(describePick("Tool", side({ selected: false, reason: "unquantified" }), undefined, "x")).toBe(
+			"Tool: no confident pick.",
+		);
+	});
+
+	it("keeps real failures, picks, and an honest none distinct", () => {
+		expect(describePick("Tool", side({ selected: false, reason: "timeout" }), undefined, "x")).toBe("Tool: no decision (timeout).");
+		expect(describePick("Tool", side({ selected: true, name: "t", confidence: 0.9 }), "t", "x")).toBe(
+			'Tool: Jev picked "t" (confidence 0.90).',
+		);
+		expect(describePick("Skill", side({ selected: false, reason: "none" }, 40, 9), undefined, "no procedure")).toContain(
+			"among 40 of 49 offered",
+		);
+	});
+});

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

@@ -10,20 +10,27 @@
  *   tools and Graft's code-context tools: they stay registered but are removed
  *   from the active tool set. Built-in tools are never touched.
  * - A compact catalog tool lists eligible tools/skills with one-line summaries.
- * - capability_discover validates one catalogued tool and activates its native
- *   definition for the current agent run; capability_skill_show loads exactly
- *   the selected skill instructions.
+ * - capability_discover readies exactly one capability. With `name` it validates
+ *   a catalogued tool and activates its native definition for the current agent
+ *   run; with `job` the agent describes what it is about to do and Jev answers,
+ *   from catalog metadata alone, which tool and which skill fit (each possibly
+ *   none), so the decision costs a bounded request instead of loading every schema. Either way the agent gets the
+ *   chosen tool's compact invocation contract, and the real schema is live on
+ *   its next turn. capability_skill_show loads exactly the selected skill
+ *   instructions.
  * - A deterministic router activates a uniquely matched tool before the run.
  *   Skills and ambiguous matches remain discoverable through the catalog
  *   without injecting fuzzy hints into the model context.
  * - Default-on Jev-assisted routing (capabilityGateway.routing.jev in settings.json)
- *   is only a bounded tie-breaker: when the deterministic router returns an
- *   ambiguous lexical hint among optional tools, the gateway offers just those
- *   hinted tools (two or three) and the current prompt to the Jev decisions
- *   model as one constrained choice question. Jev may answer `none` or one
- *   hinted canonical tool name; the gateway revalidates the choice against the
- *   live catalog and activates it for the current run only. No hint, a unique
- *   activation, a skill match, or an already-activated tool never reaches Jev.
+ *   has two callers. The host-side one is only a bounded tie-breaker: when the
+ *   deterministic router returns an ambiguous lexical hint among optional tools,
+ *   the gateway offers just those hinted tools (two or three) and the current
+ *   prompt to the Jev decisions model as one constrained choice question. The
+ *   agent-side one is capability_discover's `job` argument, which offers the
+ *   catalog metadata of every offered capability. Jev may answer `none` or one
+ *   canonical name; the gateway revalidates the choice against the live catalog
+ *   and activates it for the current run only. No hint, a unique activation, a
+ *   skill match, or an already-activated tool never reaches the host-side path.
  *   Every Jev failure is an ordinary abstention that leaves deterministic
  *   behavior in place. Without Token-In credentials, no Jev request is sent and
  *   the user is prompted to add an account with `/tokenin add`.
@@ -37,7 +44,7 @@
 
 import { readFileSync } from "node:fs";
 import { dirname } from "node:path";
-import { stripFrontmatter, type ExtensionAPI, type ToolInfo } from "@selesai/code";
+import { stripFrontmatter, type ExtensionAPI, type ExtensionContext, type ToolInfo } from "@selesai/code";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
@@ -45,24 +52,30 @@ import {
 	buildSkillCatalog,
 	buildToolCatalog,
 	BUILTIN_TOOL_NAMES,
+	firstSentence,
 	route,
 	type CatalogEntry,
 } from "./catalog.ts";
 import {
+	gatewayJevConnection,
 	hintedToolCandidates,
 	MIN_GATEWAY_JEV_CANDIDATES,
 	readGatewayJevConfig,
+	routeJobToJev,
 	routeToJevTool,
+	type JevJobPick,
 	JEV_UNAVAILABLE_REASONS,
 } from "./routing.ts";
-import { confidenceBucket } from "../jev/decisions.ts";
+import { confidenceBucket, jevUnavailable, warnJevUnavailableOnce } from "../jev/decisions.ts";
 
 export const GATEWAY_ENV = "SELESAI_CAPABILITY_GATEWAY";
 export const GATEWAY_TOOLS = new Set(["capability_catalog", "capability_discover", "capability_skill_show"]);
 
 // Graft supplies pre-turn hybrid context and must remain callable for precise
-// follow-ups; making it dormant defeats both paths.
+// 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.
 const ALWAYS_ACTIVE_EXTENSION_TOOLS = new Set([
+	"ask_jev",
 	"graft_check_freshness",
 	"graft_file_api",
 	"graft_find_all",
@@ -71,11 +84,88 @@ const ALWAYS_ACTIVE_EXTENSION_TOOLS = new Set([
 	"graft_trace_calls",
 ]);
 
-export const CAPABILITY_INSTRUCTION = `Optional capabilities (extension tools and skills) are not listed here by default. To use one:
-- Search the compact catalog with capability_catalog (kind: "tool" or "skill", natural-language query) when no active tool fits or a specialized integration/workflow is requested.
-- Activate a catalogued tool with capability_discover, then call it normally on the next turn.
-- Load a skill's full instructions with capability_skill_show before applying it.
-Never invent optional tool names, actions, or fields; discover them first.`;
+const JOB_ROUTE_LINE =
+	"- Call capability_discover with `job` (what you are about to do, in your own words) when a task may need a specialized capability you do not have active. Jev answers two things from metadata alone: which tool (callable code, usable many times) and which skill (a written procedure, read once), each possibly none. A chosen tool comes back with its parameters and is callable on your next turn; a chosen skill is loaded with capability_skill_show.";
+
+/**
+ * The single skill-index entry the gateway installs. The `job` line is offered only while Jev can
+ * answer it: telling the agent about a route that always fails costs it a turn every time.
+ */
+export function capabilityInstruction(jobRoute: boolean): string {
+	return [
+		"Optional capabilities (extension tools and skills) are not listed here by default. To use one:",
+		...(jobRoute ? [JOB_ROUTE_LINE] : []),
+		jobRoute
+			? '- Call capability_discover with an exact `name`, or search the compact catalog with capability_catalog (kind: "tool" or "skill", natural-language query) when you already know what you are looking for.'
+			: '- Search the compact catalog with capability_catalog (kind: "tool" or "skill", natural-language query), then call capability_discover with the exact `name`.',
+		"- Load a skill's full instructions with capability_skill_show before applying it.",
+		"Never invent optional tool names, actions, or fields; discover them first.",
+		"Never tell the user a tool is unavailable, or that you cannot do something, until you have checked for it here: a tool named in a message, instruction, or task that is not in your tool list is usually an optional capability, so call capability_discover with its `name` and use it.",
+	].join("\n");
+}
+
+export const CAPABILITY_INSTRUCTION = capabilityInstruction(true);
+
+/** Longest description kept in an invocation contract; the full text is live in the schema. */
+export const MAX_CONTRACT_DESCRIPTION_CHARS = 240;
+/** Longest per-parameter description kept in an invocation contract. */
+export const MAX_CONTRACT_PARAMETER_CHARS = 120;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Gateway tool results: text for the model, plus a shape-only details payload persisted in the session. */
+type ToolAnswer = { content: Array<{ type: "text"; text: string }>; details: Record<string, unknown> };
+
+function clip(text: string, max: number): string {
+	const trimmed = text.trim();
+	return trimmed.length > max ? `${trimmed.slice(0, max)}…` : trimmed;
+}
+
+/** A parameter's shape in one token; nested schemas are named, never expanded. */
+export function schemaShape(schema: Record<string, unknown>): string {
+	if (Array.isArray(schema.enum)) return schema.enum.map((value) => JSON.stringify(value)).join(" | ");
+	if (Array.isArray(schema.anyOf) || Array.isArray(schema.oneOf)) return "one of several";
+	if (schema.type === "array") {
+		const items = isRecord(schema.items) ? schema.items : {};
+		return `array<${typeof items.type === "string" ? items.type : "value"}>`;
+	}
+	return typeof schema.type === "string" ? schema.type : "value";
+}
+
+/**
+ * The compact invocation contract for one tool: what it does and the parameters it takes.
+ *
+ * Deliberately not the schema itself. An activated tool is callable on the next turn, where the
+ * provider already carries the full schema, so repeating it here would pay for the same tokens
+ * twice. This is enough to plan the call and to abandon it before loading anything.
+ */
+export function invocationContract(tool: ToolInfo): string {
+	const schema = isRecord(tool.parameters) ? tool.parameters : {};
+	const properties = isRecord(schema.properties) ? schema.properties : {};
+	const required = new Set(
+		Array.isArray(schema.required) ? schema.required.filter((name): name is string => typeof name === "string") : [],
+	);
+	const lines = [
+		`${tool.name} — ${clip(tool.discovery?.summary?.trim() || firstSentence(tool.description) || tool.name, MAX_CONTRACT_DESCRIPTION_CHARS)}`,
+	];
+	const parameters = Object.entries(properties);
+	if (parameters.length === 0) {
+		lines.push("Parameters: none");
+		return lines.join("\n");
+	}
+	lines.push("Parameters:");
+	for (const [name, raw] of parameters) {
+		const property = isRecord(raw) ? raw : {};
+		const description =
+			typeof property.description === "string"
+				? `: ${clip(firstSentence(property.description), MAX_CONTRACT_PARAMETER_CHARS)}`
+				: "";
+		lines.push(`- ${name} (${schemaShape(property)}, ${required.has(name) ? "required" : "optional"})${description}`);
+	}
+	return lines.join("\n");
+}
 
 function isEnabled(): boolean {
 	return process.env[GATEWAY_ENV] !== "0";
@@ -143,6 +233,24 @@ function emitTelemetry(pi: ExtensionAPI, event: string, data: Record<string, unk
 	}
 }
 
+/** One kind's line: the pick, `none` (honest about what Jev did not see), or why there is no answer. */
+export function describePick(label: string, side: JevJobPick, chosen: string | undefined, noneMeans: string): string {
+	const notSeen =
+		side.dropped > 0
+			? ` — among ${side.offered} of ${side.offered + side.dropped} offered; the rest were not considered, so search capability_catalog if one might fit`
+			: "";
+	if (side.pick.selected) {
+		return chosen
+			? `${label}: Jev picked "${chosen}" (confidence ${side.pick.confidence.toFixed(2)}).`
+			: `${label}: Jev picked "${side.pick.name}", which is no longer catalogued; nothing was readied.`;
+	}
+	if (side.pick.reason === "none") return `${label}: none — ${noneMeans}${notSeen}.`;
+	if (side.offered === 0) return `${label}: none catalogued.`;
+	// Jev leaned somewhere but not firmly enough to act on: for the agent that is "nothing clearly fits".
+	if (side.pick.reason === "low-confidence" || side.pick.reason === "unquantified") return `${label}: no confident pick${notSeen}.`;
+	return `${label}: no decision (${side.pick.reason}).`;
+}
+
 /** Where a run-local tool activation came from; recorded so use telemetry can attribute it. */
 type ActivationSource = "deterministic" | "jev" | "discover";
 
@@ -152,7 +260,22 @@ export default function capabilityGatewayExtension(pi: ExtensionAPI): void {
 	// Tools this gateway activated for the current run, and whether they were invoked.
 	// Cleared at agent_settled with the activations themselves.
 	const activations = new Map<string, { source: ActivationSource; used: boolean }>();
-	let tokenInSetupPrompted = false;
+	// Whether the skill index currently offers the `job` route; re-derived before every run.
+	let jobRouteOffered = true;
+
+	/** Replace the eager skill index with one compact capability entry. Full instructions load only on show. */
+	function installSkillIndex(): void {
+		pi.setSkillsIndexFilter(() => [
+			{
+				name: "capability-gateway",
+				description: capabilityInstruction(jobRouteOffered),
+				filePath: "<capability-gateway>",
+				baseDir: "<capability-gateway>",
+				sourceInfo: { path: "<capability-gateway>", source: "builtin", scope: "user", origin: "top-level" },
+				disableModelInvocation: false,
+			},
+		]);
+	}
 
 	/** Activate one tool for the current run, keeping the rest of the loadout untouched. */
 	function activateTool(name: string, source: ActivationSource): void {
@@ -173,18 +296,7 @@ export default function capabilityGatewayExtension(pi: ExtensionAPI): void {
 			(name) => !eligibleTools(pi).some((tool) => tool.name === name),
 		);
 		pi.setActiveTools(keep);
-		// Replace the eager skill index with a single compact capability
-		// instruction entry. Full skill instructions load only on show/invoke.
-		pi.setSkillsIndexFilter(() => [
-			{
-				name: "capability-gateway",
-				description: CAPABILITY_INSTRUCTION,
-				filePath: "<capability-gateway>",
-				baseDir: "<capability-gateway>",
-				sourceInfo: { path: "<capability-gateway>", source: "builtin", scope: "user", origin: "top-level" },
-				disableModelInvocation: false,
-			},
-		]);
+		installSkillIndex();
 		emitTelemetry(pi, "session_start", { baselineCount: baseline.length, dormantCount: baseline.length - keep.length });
 		void ctx;
 	});
@@ -202,7 +314,7 @@ export default function capabilityGatewayExtension(pi: ExtensionAPI): void {
 			query: Type.Optional(Type.String({ minLength: 1, description: "Natural-language query; omit to list all." })),
 			kind: Type.Optional(StringEnum(["tool", "skill"] as const, { description: "Filter by capability kind." })),
 		}),
-		async execute(_id, params) {
+		async execute(_id, params): Promise<ToolAnswer> {
 			const entries = catalogEntries(pi);
 			const filtered = entries.filter(
 				(entry) => !params.kind || entry.kind === params.kind,
@@ -240,39 +352,161 @@ export default function capabilityGatewayExtension(pi: ExtensionAPI): void {
 		},
 	});
 
+	/** Make one catalogued tool callable for this run and return how to invoke it. */
+	function readyTool(entry: CatalogEntry, source: ActivationSource): string {
+		// Already in the loadout (routed before the turn, or discovered earlier): re-activating would
+		// only misattribute it, and repeating the contract teaches nothing. Say what the pick means.
+		if (pi.getActiveTools().includes(entry.name)) {
+			return `"${entry.name}" is already active, so nothing changed. If it failed, the problem is in the tool itself (its error says what), not in choosing it: fix that, or pick a different capability by name.`;
+		}
+		activateTool(entry.name, source);
+		const tool = eligibleTools(pi).find((candidate) => candidate.name === entry.name);
+		return [
+			`Activated "${entry.name}" for this run: call it on your next turn, with its full schema live in your tool list.`,
+			"",
+			tool ? invocationContract(tool) : `${entry.name} — ${entry.summary}`,
+		].join("\n");
+	}
+
+	/**
+	 * The agent's on-demand route. Jev decides over catalog metadata only, so the decision costs one
+	 * bounded request instead of every schema. A tool and a skill are separate answers: a picked tool
+	 * is activated with its invocation contract, a picked skill is named for capability_skill_show.
+	 */
+	async function discoverByJob(job: string, kind: "tool" | "skill" | "both", ctx: ExtensionContext): Promise<ToolAnswer> {
+		const answer = (text: string, details: Record<string, unknown> = {}): ToolAnswer => ({
+			content: [{ type: "text" as const, text }],
+			details,
+		});
+		const config = readGatewayJevConfig();
+		if (!config.enabled) {
+			return answer(
+				"Jev capability routing is off (capabilityGateway.routing.jev.enabled is false). Browse with capability_catalog and pass an exact `name`.",
+			);
+		}
+		const entries = catalogEntries(pi);
+		const tools = kind === "skill" ? [] : entries.filter((entry) => entry.kind === "tool");
+		const skills = kind === "tool" ? [] : entries.filter((entry) => entry.kind === "skill");
+		const route = await routeJobToJev(tools, skills, job, ctx, config);
+		if (route.tool.offered + route.skill.offered === 0) {
+			return answer(
+				"No catalogued capability fits one decision request. Narrow it with capability_catalog and pass an exact `name`.",
+			);
+		}
+
+		// Revalidate each accepted name against the live catalog: one that vanished mid-call is gone.
+		const live = catalogEntries(pi);
+		const resolve = ({ pick }: JevJobPick, of: "tool" | "skill") =>
+			pick.selected ? live.find((entry) => entry.kind === of && entry.name === pick.name) : undefined;
+		const tool = resolve(route.tool, "tool");
+		const skill = resolve(route.skill, "skill");
+		// Jev could not be reached at all (as opposed to answering `none`): one reason covers both questions.
+		const unavailable = [route.tool.pick, route.skill.pick].flatMap((pick) =>
+			!pick.selected && JEV_UNAVAILABLE_REASONS.has(pick.reason) ? [pick.reason] : [],
+		)[0];
+		emitTelemetry(pi, "route", {
+			source: "agent",
+			outcome: tool || skill ? "selected" : unavailable ? "unavailable" : "abstained",
+			...(tool ? { tool: tool.name } : {}),
+			...(skill ? { skill: skill.name } : {}),
+			candidates: route.tool.offered + route.skill.offered,
+			dropped: route.tool.dropped + route.skill.dropped,
+			durationMs: route.elapsedMs,
+		});
+		if (!tool && !skill && (unavailable === "no-credential" || unavailable === "no-template")) {
+			if (ctx.hasUI) warnJevUnavailableOnce(ctx.ui, config.provider);
+			return answer(
+				"Choosing by `job` needs Jev, which has no credential in this session. Search capability_catalog and pass an exact `name` instead, or use the built-in tools.",
+				{ selected: false, reason: unavailable },
+			);
+		}
+		if (!tool && !skill && unavailable) {
+			return answer(
+				`Jev could not decide this job (${unavailable}). Browse with capability_catalog and pass an exact \`name\`, or use the built-in tools.`,
+				{ selected: false, reason: unavailable },
+			);
+		}
+
+		const lines: string[] = [];
+		const details: Record<string, unknown> = { selected: Boolean(tool || skill) };
+		if (kind !== "skill") {
+			lines.push(describePick("Tool", route.tool, tool?.name, "the built-in tools (read, bash, edit, write, grep, find, ls) or a direct answer are enough"));
+			details.tool = tool?.name ?? null;
+		}
+		if (kind !== "tool") {
+			lines.push(describePick("Skill", route.skill, skill?.name, "no written procedure is needed"));
+			if (skill) lines.push(`  ${skill.summary}\n  Load it with capability_skill_show before applying it.`);
+			details.skill = skill?.name ?? null;
+		}
+		if (tool) lines.push("", readyTool(tool, "jev"));
+		return answer(lines.join("\n"), details);
+	}
+
 	pi.registerTool({
 		name: "capability_discover",
 		label: "Capability Discover",
 		description:
-			"Activate one catalogued extension tool for the current agent run. The tool's real schema and validation contract become available on the next model turn; it is removed again when the run ends. Use the exact name from capability_catalog.",
-		promptSnippet: "Activate a catalogued extension tool for the current run",
+			"Ready optional capabilities without loading them. Pass `job` (what you are about to do) and Jev answers, from catalog metadata alone, which tool (callable code from an extension or MCP server, usable many times) and which skill (a written procedure from a user, agent, or teammate, read once) fit it — each may be `none`. A chosen tool is activated for this run and its parameters are returned, so you can call it on your next turn; a chosen skill comes back by name for capability_skill_show. Pass `name` instead when capability_catalog already gave you one.",
+		promptSnippet: "Let Jev pick the capability for a job (or name one), then see how to invoke it",
 		parameters: Type.Object({
-			name: Type.String({ minLength: 1, description: "Exact catalogued tool name." }),
+			job: Type.Optional(
+				Type.String({ minLength: 1, description: "What you are about to do, in your own words. Jev picks the capability." }),
+			),
+			name: Type.Optional(Type.String({ minLength: 1, description: "Exact catalogued name, when you already know it." })),
+			kind: Type.Optional(
+				StringEnum(["tool", "skill", "both"] as const, {
+					description: "Ask only about tools or only about skills. Default: both, answered separately.",
+				}),
+			),
 		}),
-		async execute(_id, params) {
+		async execute(_id, params, _signal, _onUpdate, ctx: ExtensionContext): Promise<ToolAnswer> {
+			const job = params.job?.trim();
+			const name = params.name?.trim();
+			if (job && name) {
+				return {
+					content: [{ type: "text", text: "Pass either `job` (let Jev choose) or `name` (you know it), not both." }],
+					details: {},
+				};
+			}
+			if (job) return discoverByJob(job, params.kind ?? "both", ctx);
+			if (!name) {
+				return {
+					content: [
+						{ type: "text", text: "Pass `job` to have Jev choose a capability, or `name` from the catalog." },
+					],
+					details: {},
+				};
+			}
+
 			const entries = catalogEntries(pi);
-			const entry = findEntry(entries, params.name);
-			if (!entry || entry.kind !== "tool") {
+			const entry = findEntry(entries, name);
+			if (!entry) {
 				return {
 					content: [
 						{
 							type: "text",
-							text: `Unknown tool "${params.name}". Search capability_catalog for the exact name, or refine your query.`,
+							text: `Unknown capability "${name}". Search capability_catalog for the exact name, or pass a \`job\` and let Jev choose.`,
 						},
 					],
 					details: { activated: false },
 				};
 			}
-			activateTool(entry.name, "discover");
-			emitTelemetry(pi, "discover", { tool: entry.name });
+			if (entry.kind === "skill") {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `"${entry.name}" is a skill: call capability_skill_show with that name to load its instructions.`,
+						},
+					],
+					details: { activated: false, skill: entry.name },
+				};
+			}
+			emitTelemetry(pi, "discover", { source: "name", tool: entry.name });
+			const alreadyActive = pi.getActiveTools().includes(entry.name);
 			return {
-				content: [
-					{
-						type: "text",
-						text: `Activated "${entry.name}" for this run. Call it normally on the next turn; it is removed when the run ends.`,
-					},
-				],
-				details: { activated: true, tool: entry.name },
+				content: [{ type: "text", text: readyTool(entry, "discover") }],
+				details: { activated: true, tool: entry.name, ...(alreadyActive ? { alreadyActive: true } : {}) },
 			};
 		},
 	});
@@ -286,7 +520,7 @@ export default function capabilityGatewayExtension(pi: ExtensionAPI): void {
 		parameters: Type.Object({
 			name: Type.String({ minLength: 1, description: "Exact skill name." }),
 		}),
-		async execute(_id, params) {
+		async execute(_id, params): Promise<ToolAnswer> {
 			const skill = pi.getResolvedSkills().find((s) => s.name === params.name);
 			if (!skill) {
 				return {
@@ -324,6 +558,15 @@ export default function capabilityGatewayExtension(pi: ExtensionAPI): void {
 	// only a bounded tie-breaker for its ambiguous/hint result.
 	// ------------------------------------------------------------------
 	pi.on("before_agent_start", async (event, ctx) => {
+		// Offer the `job` route only while Jev can answer it; `/tokenin add` brings it back on the
+		// next run without a reload. Silent: the warning belongs to a path that actually needed Jev.
+		const jevConfig = readGatewayJevConfig();
+		const jobReady = jevConfig.enabled && (await jevUnavailable(ctx, gatewayJevConnection(jevConfig))) === undefined;
+		if (jobReady !== jobRouteOffered) {
+			jobRouteOffered = jobReady;
+			installSkillIndex();
+		}
+
 		const entries = catalogEntries(pi);
 		const result = routePrompt(event.prompt, entries);
 		if (result.action === "activate" && result.entry) {
@@ -351,16 +594,8 @@ export default function capabilityGatewayExtension(pi: ExtensionAPI): void {
 		emitTelemetry(pi, "route", { source: "jev", outcome: "attempt", candidates: candidates.length });
 		const jevRoute = await routeToJevTool(candidates, event.prompt, ctx, config);
 		if (!jevRoute.selected) {
-			if (
-				!tokenInSetupPrompted &&
-				config.provider === "tokenin" &&
-				(jevRoute.reason === "no-credential" || jevRoute.reason === "no-template")
-			) {
-				tokenInSetupPrompted = true;
-				ctx.ui.notify(
-					"Jev tool tie-breaking needs a Token-In account. Add one with /tokenin add; deterministic routing will keep working meanwhile.",
-					"warning",
-				);
+			if ((jevRoute.reason === "no-credential" || jevRoute.reason === "no-template") && ctx.hasUI) {
+				warnJevUnavailableOnce(ctx.ui, config.provider);
 			}
 			emitTelemetry(pi, "route", {
 				source: "jev",