{"record":{"id":"bf82aba4750b923c","repo":"can1357/oh-my-pi","slug":"unknown-agent-agentname-available-availab","errorCode":null,"errorMessage":"Unknown agent \"${agentName}\". Available: ${available}","messagePattern":"Unknown agent \"(.+?)\"\\. Available: (.+?)","errorType":"validation","errorClass":"StructuredSubagentError","httpStatus":null,"severity":"error","filePath":"packages/coding-agent/src/task/structured-subagent.ts","lineNumber":259,"sourceCode":" * Resolve every policy shared by task and eval before allocating artifacts or\n * dispatching work. Callers translate {@link StructuredSubagentError} into\n * their own wire-level error surface.\n */\nexport async function resolveEffectiveSubagentPolicy(\n\trequest: StructuredSubagentRequest,\n): Promise<EffectiveSubagentPolicy> {\n\tawait request.session.settings.reloadFromDisk();\n\tconst spawnPolicy = resolveSpawnPolicy(request.session.getSessionSpawns());\n\tconst agentName = request.agent?.trim() || spawnPolicy.defaultAgent;\n\tconst planMode = request.session.getPlanModeState?.()?.enabled === true;\n\tassertPlanControlsAllowed(request, planMode);\n\tassertDepthAndSpawnAllowed(request, agentName);\n\n\tconst discovery = await discoverAgents(request.session.cwd, undefined, request.session.effectiveExtensionRoots?.());\n\tconst agent = getAgent(discovery.agents, agentName);\n\tif (!agent) {\n\t\tconst available = discovery.agents.map(candidate => candidate.name).join(\", \") || \"none\";\n\t\tthrow new StructuredSubagentError(\"preflight\", `Unknown agent \"${agentName}\". Available: ${available}`);\n\t}\n\tconst disabledAgents = request.session.settings.get(\"task.disabledAgents\") as string[];\n\tif (disabledAgents.includes(agentName)) {\n\t\tconst enabled = discovery.agents\n\t\t\t.filter(candidate => !disabledAgents.includes(candidate.name))\n\t\t\t.map(candidate => candidate.name);\n\t\tthrow new StructuredSubagentError(\n\t\t\t\"preflight\",\n\t\t\t`Agent \"${agentName}\" is disabled in settings. Enable it via /agents, or use a different agent type.${enabled.length > 0 ? ` Available: ${enabled.join(\", \")}` : \"\"}`,\n\t\t);\n\t}\n\n\tconst effectiveAgent = planMode ? createPlanModeAgent(agent) : agent;\n\tconst schema = resolveSchema(request, effectiveAgent);\n\tif (schema.source === \"caller\" || (schema.source !== \"none\" && schema.mode === \"strict\")) {\n\t\tconst { error } = buildOutputValidator(schema.schema);\n\t\tif (error) {\n\t\t\tconst scope =","sourceCodeStart":241,"sourceCodeEnd":277,"githubUrl":"https://github.com/can1357/oh-my-pi/blob/969062200754ea02cfac922e5ebb8c608c079e15/packages/coding-agent/src/task/structured-subagent.ts#L241-L277","documentation":"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').","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use one of the agent names listed in the error's `Available:` text","Define the agent (e.g. .omp/agent markdown or configured agent file) in a location discoverAgents scans","Ensure the session cwd / extension roots point at the project containing the agent definition"],"exampleFix":"// before\nawait task({ agent: \"code-review\" });\n// after (matches discovered agent)\nawait task({ agent: \"reviewer\" });","handlingStrategy":"validation","validationCode":"import { discoverAgents, getAgent } from \"...\";\nconst discovery = await discoverAgents(session.cwd, undefined, session.effectiveExtensionRoots?.());\nif (!getAgent(discovery.agents, agentName)) {\n  throw new Error(`Unknown agent \"${agentName}\". Available: ${discovery.agents.map(a => a.name).join(\", \") || \"none\"}`);\n}\nawait task({ agent: agentName });","typeGuard":null,"tryCatchPattern":"try {\n  await task(req);\n} catch (e) {\n  if (e instanceof StructuredSubagentError && e.message.includes(\"Unknown agent\")) {\n    const available = e.message.split(\"Available:\")[1]?.trim() ?? \"none\";\n    return task({ ...req, agent: available.split(\", \")[0] });\n  }\n  throw e;\n}","preventionTips":["Discover agents at workflow start and validate every referenced name","Keep agent definitions under paths covered by cwd/extension roots","Rename agents atomically with all prompts referencing them"],"tags":["subagent","unknown-agent","discovery","preflight"],"backgroundTag":"unknown-agent-name","analyzedSha":"969062200754ea02cfac922e5ebb8c608c079e15","analyzedAt":"2026-08-31T10:29:35.737Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}