can1357/oh-my-pi · error · StructuredSubagentError

Unknown agent "${agentName}". Available: ${available}

Error message

Unknown agent "${agentName}". Available: ${available}

What it means

Thrown in preflight when the requested agent name does not resolve to any discovered agent. `discoverAgents` scans the session cwd and extension roots; if `getAgent` finds no match, the error lists all discovered agent names (or 'none').

Source

Thrown at packages/coding-agent/src/task/structured-subagent.ts:259

 * Resolve every policy shared by task and eval before allocating artifacts or
 * dispatching work. Callers translate {@link StructuredSubagentError} into
 * their own wire-level error surface.
 */
export async function resolveEffectiveSubagentPolicy(
	request: StructuredSubagentRequest,
): Promise<EffectiveSubagentPolicy> {
	await request.session.settings.reloadFromDisk();
	const spawnPolicy = resolveSpawnPolicy(request.session.getSessionSpawns());
	const agentName = request.agent?.trim() || spawnPolicy.defaultAgent;
	const planMode = request.session.getPlanModeState?.()?.enabled === true;
	assertPlanControlsAllowed(request, planMode);
	assertDepthAndSpawnAllowed(request, agentName);

	const discovery = await discoverAgents(request.session.cwd, undefined, request.session.effectiveExtensionRoots?.());
	const agent = getAgent(discovery.agents, agentName);
	if (!agent) {
		const available = discovery.agents.map(candidate => candidate.name).join(", ") || "none";
		throw new StructuredSubagentError("preflight", `Unknown agent "${agentName}". Available: ${available}`);
	}
	const disabledAgents = request.session.settings.get("task.disabledAgents") as string[];
	if (disabledAgents.includes(agentName)) {
		const enabled = discovery.agents
			.filter(candidate => !disabledAgents.includes(candidate.name))
			.map(candidate => candidate.name);
		throw new StructuredSubagentError(
			"preflight",
			`Agent "${agentName}" is disabled in settings. Enable it via /agents, or use a different agent type.${enabled.length > 0 ? ` Available: ${enabled.join(", ")}` : ""}`,
		);
	}

	const effectiveAgent = planMode ? createPlanModeAgent(agent) : agent;
	const schema = resolveSchema(request, effectiveAgent);
	if (schema.source === "caller" || (schema.source !== "none" && schema.mode === "strict")) {
		const { error } = buildOutputValidator(schema.schema);
		if (error) {
			const scope =

View on GitHub (pinned to 9690622007)

Solutions

  1. Use one of the agent names listed in the error's `Available:` text
  2. Define the agent (e.g. .omp/agent markdown or configured agent file) in a location discoverAgents scans
  3. Ensure the session cwd / extension roots point at the project containing the agent definition

Example fix

// before
await task({ agent: "code-review" });
// after (matches discovered agent)
await task({ agent: "reviewer" });
Defensive patterns

Strategy: validation

Validate before calling

import { discoverAgents, getAgent } from "...";
const discovery = await discoverAgents(session.cwd, undefined, session.effectiveExtensionRoots?.());
if (!getAgent(discovery.agents, agentName)) {
  throw new Error(`Unknown agent "${agentName}". Available: ${discovery.agents.map(a => a.name).join(", ") || "none"}`);
}
await task({ agent: agentName });

Try / catch

try {
  await task(req);
} catch (e) {
  if (e instanceof StructuredSubagentError && e.message.includes("Unknown agent")) {
    const available = e.message.split("Available:")[1]?.trim() ?? "none";
    return task({ ...req, agent: available.split(", ")[0] });
  }
  throw e;
}

Prevention

When it happens

Trigger: Calling the task tool with `agent: "typo-name"` or an agent defined only in a directory that is not the session cwd / extension roots; agent markdown/definition file missing or renamed.

Common situations: Typos in the agent name; agent definitions living in a project not covered by discovery (wrong cwd, extension root not loaded); an agent deleted or renamed in a refactor while prompts still reference the old name.

Related errors

AI-assisted analysis of can1357/oh-my-pi@9690622007 (2026-08-31). Data as JSON: /api/errors/bf82aba4750b923c. Report an issue: GitHub.