All contributors have signed the CLA. Thank you! ✅
_{Posted by the CLA Assistant Lite bot.}

I have read the CLA Document and I hereby sign the CLA

recheck

@cubic-dev which path is better using the display name or the id?
which solution is the cleanest and the right one long term?

@cubic-dev which path is better using the display name or the id?
which solution is the cleanest and the right one long term?

@RaviTharuma In the current architecture of Opencode, using the display name (which often acts as the registration key) is the correct path because that is what the backend uses as the primary identifier.

The Trade-off

• Display Name (Current Solution): This is necessary right now because the API expects a match against the strings listed in the error message (e.g., "Prometheus (Plan Builder)"). In Opencode, agents are identified by their registration record keys rather than a separate hidden ID field. If you pass the internal slug (prometheus), the registry lookup fails.
• Internal ID/Slug (Long-term Ideal): Conventionally, using a stable, machine-readable ID (like prometheus) is "cleaner" because it doesn't break if someone decides to rename the agent's display label. However, implementing this would require a change to the backend registry to support aliasing or a dedicated id field.

Recommendation for this PR

The current solution using getAgentDisplayName is the right one for this fix. It correctly maps the internal reference to the string the API is keyed on.

Long-term improvement:
If the team wants to make the system more resilient to UI changes, the "cleanest" evolution would be:

1. Update the agent registration to include both a stable id (slug) and a displayName.
2. Update the backend to resolve the agent field in promptAsync by checking the id first, then falling back to the registration key.

Since the immediate goal is to fix the "Agent not found" error during runtime-fallback, your change is the pragmatic and correct way to align with the existing SDK behavior.

For more details on how agents are registered and identified, you can check the Core Architecture or the repository learnings regarding agent configuration.

@cubic-dev

So we should take the display name because OpenCode itself does not even use the ID.
Although the ID would be the cleanest solution. Is this what you are saying?

@cubic-dev

So we should take the display name because OpenCode itself does not even use the ID.
Although the ID would be the cleanest solution. Is this what you are saying?

@RaviTharuma Exactly. To clarify, what we call the "ID" or "slug" internally (like sisyphus or prometheus) is essentially invisible to the OpenCode backend's agent registry. The backend only knows about the agents by the keys they were registered with, which are their full display names (e.g., Sisyphus (Ultraworker)).

So, while using a stable, machine-readable ID is the better engineering practice for the long term, it isn't currently an option without changing how the backend identifies agents.

This matches our repository learnings which note that agents are identified by their registration record key rather than a specific ID property. Your current fix is the correct way to handle this given the current architecture.